{ "openapi": "3.2.0", "info": { "title": "NIC Monaco Registrar API", "version": "1.0.0", "description": "Official integration API of the NIC Monaco registrar portal for accredited\nregistrars: management of domain names, contacts and the registrar profile,\nand follow-up of requests.\n\n## Authentication\n\nEvery request must carry an API token in the HTTP header:\n\n```\nAuthorization: Bearer ksl_...\n```\n\nTokens are created in the registrar portal (**Settings → API tokens**,\npage `/api-tokens`). A token is displayed only once, when it is created:\nstore it in a secrets vault. It can be revoked at any time from the same\npage. At most 5 active tokens per registrar.\n\n## Scopes and permissions\n\n* `read`: read access (all `GET` routes).\n* `write`: submitting requests (all `POST` routes), to be ticked when the\n token is created.\n\nA token acts **on behalf of the user who created it** and inherits their\npermissions in the registrar portal (e.g. `domains.register`,\n`contacts.manage`). It can never do more than that user. If the creator is\nblocked or leaves the registrar, the token stops working.\n\nEvery response is limited to the registrar owning the token: a domain, a\ncontact or a request belonging to another registrar returns `404`.\n\n## Requests and registry validation\n\nAs in the web interface, **no change is applied immediately**: each `POST`\nroute creates a *request* (`202` response with a `request_id`) that the\nregistry approves or rejects. Track it with\n`GET /api/v1/requests/detail?id=…`. While a request is pending, the\nresources expose the requested values in `pending_changes`.\n\n## Quotas\n\n600 requests per hour and per token (HTTP 429 with a Retry-After header\nbeyond that). Automating the web interface (outside the API) is forbidden.\n\n## Format\n\nJSON request bodies (`Content-Type: application/json`), UTF-8 JSON\nresponses. Errors follow the `Error` schema:\n`{\"error\": \"\", \"message\": \"\", \"details\": {…}}` — `details`\nlists the errors per field for `422` responses. Error messages are\nreturned in French.\n" }, "servers": [ { "url": "/", "description": "Current server (same domain as the registrar portal)" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account", "description": "Token identity and diagnostics" }, { "name": "Registrar", "description": "Registrar profile" }, { "name": "Domains", "description": "Reading and requests on the registrar's domain names" }, { "name": "Contacts", "description": "Registrar's contacts (holders, administrative and technical contacts)" }, { "name": "Requests", "description": "Follow-up and cancellation of submitted requests" } ], "paths": { "/api/v1/me": { "get": { "tags": [ "Account" ], "summary": "Token identity", "description": "Registrar, user and scopes of the token. Recommended endpoint to validate an integration.", "operationId": "getMe", "responses": { "200": { "description": "Token identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/registrar": { "get": { "tags": [ "Registrar" ], "summary": "Registrar profile", "description": "Registrar contact details and changes awaiting validation. Scope `read`.", "operationId": "getRegistrar", "responses": { "200": { "description": "Registrar profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registrar" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/registrar/update": { "post": { "tags": [ "Registrar" ], "summary": "Request a change to the registrar profile", "description": "Only the provided fields are changed. Scope `write`, permission `registrar.manage`.", "operationId": "updateRegistrar", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrarUpdate" }, "example": { "phone": "+377 93 00 00 00", "billing_email": "billing@registrar.mc" } } } }, "responses": { "200": { "$ref": "#/components/responses/NoChange" }, "202": { "$ref": "#/components/responses/RequestCreated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/api/v1/domains": { "get": { "tags": [ "Domains" ], "summary": "List the registrar's domains", "description": "Domains of the registrar (archived ones excluded), sorted by name. Scope `read`, permission `domains.view`.", "operationId": "listDomains", "responses": { "200": { "description": "Registrar's domains", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/domains/detail": { "get": { "tags": [ "Domains" ], "summary": "Domain details", "description": "Contacts, name servers, DNSSEC, pending changes and effective state\n(stored values + pending requests). Scope `read`, permission `domains.view`.\n", "operationId": "getDomain", "parameters": [ { "$ref": "#/components/parameters/DomainQuery" } ], "responses": { "200": { "description": "Domain details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/domains/check": { "get": { "tags": [ "Domains" ], "summary": "Check whether a name is available", "description": "Same checks as the registration form. Scope `read`.", "operationId": "checkDomain", "parameters": [ { "$ref": "#/components/parameters/DomainQuery" } ], "responses": { "200": { "description": "Check result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainCheck" }, "examples": { "available": { "value": { "domain": "new-name.mc", "available": true, "reason": null } }, "taken": { "value": { "domain": "example.mc", "available": false, "reason": "already_registered" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/domains/create": { "post": { "tags": [ "Domains" ], "summary": "Request a domain registration", "description": "The three contacts must belong to the registrar (a contact whose\ncreation is pending is accepted). At least two name servers, eight at\nmost. `auto_renew` defaults to the registrar setting.\nScope `write`, permission `domains.register`.\n", "operationId": "createDomain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainCreate" }, "example": { "domain": "new-name.mc", "auto_renew": true, "contacts": { "holder": "DUPO1-MC", "admin": "DUPO1-MC", "tech": "TECH3-MC" }, "nameservers": [ "ns1.host.mc", "ns2.host.mc" ] } } } }, "responses": { "202": { "$ref": "#/components/responses/RequestCreated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/api/v1/domains/update": { "post": { "tags": [ "Domains" ], "summary": "Request a domain change", "description": "Only the provided fields are changed. `nameservers` replaces the whole\nlist; `dnssec: null` removes DNSSEC. Rejected (409) if the domain is\nfrozen, blocked, expired, deleted or being transferred.\nScope `write`, permission `domains.register`.\n", "operationId": "updateDomain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainUpdate" }, "example": { "domain": "example.mc", "contacts": { "tech": "TECH3-MC" }, "nameservers": [ "ns1.new-host.mc", "ns2.new-host.mc" ] } } } }, "responses": { "200": { "$ref": "#/components/responses/NoChange" }, "202": { "$ref": "#/components/responses/RequestCreated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/api/v1/domains/renew": { "post": { "tags": [ "Domains" ], "summary": "Request a domain renewal (1 year)", "description": "Possible when the expiry date is less than 365 days away. An active\nautomatic renewal is turned off in the same request.\nScope `write`, permission `domains.renew`.\n", "operationId": "renewDomain", "requestBody": { "$ref": "#/components/requestBodies/DomainOnly" }, "responses": { "202": { "description": "Request created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RequestCreated" }, { "type": "object", "properties": { "new_expires_at": { "type": "string", "format": "date", "example": "2028-03-14" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/domains/delete": { "post": { "tags": [ "Domains" ], "summary": "Request a domain deletion", "description": "Scope `write`, permission `domains.delete`.", "operationId": "deleteDomain", "requestBody": { "$ref": "#/components/requestBodies/DomainOnly" }, "responses": { "202": { "$ref": "#/components/responses/RequestCreated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/domains/reactivate": { "post": { "tags": [ "Domains" ], "summary": "Request the reactivation of an expired or deleted domain", "description": "Scope `write`, permission `domains.renew`.", "operationId": "reactivateDomain", "requestBody": { "$ref": "#/components/requestBodies/DomainOnly" }, "responses": { "202": { "$ref": "#/components/responses/RequestCreated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/domains/authcode": { "post": { "tags": [ "Domains" ], "summary": "Generate a transfer code", "description": "Code valid for 48 hours, to be given to the gaining registrar. It is\nreturned only once (stored hashed); generating a new one cancels the\nprevious one. Scope `write`, permission `domains.authcode`.\n", "operationId": "createAuthCode", "requestBody": { "$ref": "#/components/requestBodies/DomainOnly" }, "responses": { "201": { "description": "Code generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthCode" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/domains/authcode/cancel": { "post": { "tags": [ "Domains" ], "summary": "Cancel the active transfer code", "description": "Scope `write`, permission `domains.authcode`.", "operationId": "cancelAuthCode", "requestBody": { "$ref": "#/components/requestBodies/DomainOnly" }, "responses": { "200": { "description": "Code cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelled": { "type": "boolean", "example": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/domains/transfer": { "post": { "tags": [ "Domains" ], "summary": "Request an inbound domain transfer", "description": "Transfers a domain from another registrar to the token's registrar,\nusing the code provided by the losing registrar (consumed when the\nrequest is recorded). The contacts must belong to your registrar:\ncreate them first with `POST /api/v1/contacts/create` if needed.\nScope `write`, permission `domains.transfer`.\n", "operationId": "transferDomain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainTransfer" }, "example": { "domain": "example.mc", "auth_code": "48213907561234098765", "contacts": { "holder": "DUPO1-MC", "admin": "DUPO1-MC", "tech": "TECH3-MC" }, "nameservers": [ "ns1.host.mc", "ns2.host.mc" ] } } } }, "responses": { "202": { "$ref": "#/components/responses/RequestCreated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/api/v1/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List the registrar's contacts", "description": "Search on nichandle, last name, first name or email. Scope `read`, permission `contacts.view`.", "operationId": "listContacts", "parameters": [ { "name": "query", "in": "query", "schema": { "type": "string" }, "description": "Search text" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Registrar's contacts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/contacts/detail": { "get": { "tags": [ "Contacts" ], "summary": "Contact details", "description": "Contact details, pending changes and the registrar's domains using the contact. Scope `read`, permission `contacts.view`.", "operationId": "getContact", "parameters": [ { "$ref": "#/components/parameters/NichandleQuery" } ], "responses": { "200": { "description": "Contact details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/contacts/create": { "post": { "tags": [ "Contacts" ], "summary": "Request a contact creation", "description": "Last name or company required; email or phone required. The nichandle\nis assigned immediately: it can be used straight away in a\nregistration or transfer request. Scope `write`, permission `contacts.manage`.\n", "operationId": "createContact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreate" }, "example": { "last_name": "Dupont", "first_name": "Marie", "address1": "1 avenue des Fleurs", "postal_code": "98000", "city": "Monaco", "country": "MC", "email": "marie.dupont@example.mc" } } } }, "responses": { "202": { "description": "Request created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RequestCreated" }, { "type": "object", "properties": { "nichandle": { "type": "string", "example": "DUPO1-MC" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/api/v1/contacts/update": { "post": { "tags": [ "Contacts" ], "summary": "Request a contact change", "description": "Only the provided fields are changed. Last name, first name and company\ncannot be changed after creation (422). Scope `write`, permission `contacts.manage`.\n", "operationId": "updateContact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdate" }, "example": { "nichandle": "DUPO1-MC", "email": "new.address@example.mc" } } } }, "responses": { "200": { "$ref": "#/components/responses/NoChange" }, "202": { "$ref": "#/components/responses/RequestCreated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/api/v1/contacts/delete": { "post": { "tags": [ "Contacts" ], "summary": "Request a contact deletion", "description": "Not possible while the contact is linked to a domain (409). Scope `write`, permission `contacts.manage`.", "operationId": "deleteContact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "nichandle" ], "properties": { "nichandle": { "type": "string", "example": "DUPO1-MC" } } } } } }, "responses": { "202": { "$ref": "#/components/responses/RequestCreated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/requests": { "get": { "tags": [ "Requests" ], "summary": "List the registrar's requests", "description": "Pending (default) or processed requests, most recent first. Scope `read`, permission `requests.view`.", "operationId": "listRequests", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "completed" ], "default": "pending" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/requests/detail": { "get": { "tags": [ "Requests" ], "summary": "Request details", "description": "Status and list of requested changes. For an inbound transfer, the\nprevious values of the losing registrar (registrar, contacts) are not\ndisclosed. Scope `read`, permission `requests.view`.\n", "operationId": "getRequest", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "integer", "example": 260930004 } } ], "responses": { "200": { "description": "Request details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/requests/cancel": { "post": { "tags": [ "Requests" ], "summary": "Cancel a pending request", "description": "Only for requests created by the token's user and not yet processed.\nRelated supporting documents are deleted. Scope `write`, permission `requests.delete`.\n", "operationId": "cancelRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "example": 260930004 } } } } } }, "responses": { "200": { "description": "Request cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "integer" }, "cancelled": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Registrar API token (`ksl_` followed by 64 hexadecimal characters), created on /api-tokens." } }, "parameters": { "DomainQuery": { "name": "domain", "in": "query", "required": true, "description": "Full domain name", "schema": { "type": "string", "example": "example.mc" } }, "NichandleQuery": { "name": "nichandle", "in": "query", "required": true, "schema": { "type": "string", "example": "DUPO1-MC" } }, "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } }, "requestBodies": { "DomainOnly": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "example.mc" } } } } } } }, "responses": { "RequestCreated": { "description": "Request created, awaiting validation by the registry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestCreated" } } } }, "NoChange": { "description": "No difference with the current state, no request created", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": [ "integer", "null" ], "example": null }, "message": { "type": "string", "example": "Aucune modification" } } } } } }, "BadRequest": { "description": "Missing or malformed parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "message": "Paramètre 'domain' manquant" } } } }, "Unauthorized": { "description": "Missing, invalid, revoked or expired token, or inactive creator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unauthorized", "message": "Jeton invalide, révoqué ou expiré" } } } }, "Forbidden": { "description": "Insufficient token scope or creator permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "forbidden", "message": "Scope 'write' requis pour ce jeton" } } } }, "NotFound": { "description": "Resource does not exist or belongs to another registrar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "not_found", "message": "Domaine introuvable pour ce bureau" } } } }, "Conflict": { "description": "Operation not possible in the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "conflict", "message": "Renouvellement impossible : expiration à plus de 365 jours" } } } }, "ValidationFailed": { "description": "Data rejected; `details` lists the errors per field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "validation_failed", "message": "Demande refusée", "details": { "domain": "Ce domaine est déjà enregistré", "nameservers.1": "Serveur DNS invalide : ns2" } } } } }, "TooManyRequests": { "description": "Hourly token quota reached (600 requests per hour)", "headers": { "Retry-After": { "description": "Suggested delay before retrying, in seconds", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "too_many_requests", "message": "Quota horaire du jeton atteint" } } } } }, "schemas": { "Me": { "type": "object", "properties": { "registrar_id": { "type": "integer", "example": 42 }, "registrar": { "type": [ "string", "null" ], "description": "Registrar nichandle", "example": "REGISTRAR-NIC" }, "token_label": { "type": "string", "example": "ERP sync" }, "acting_as": { "type": "string", "description": "User on whose behalf the token acts", "example": "JDUP1-MC" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "write" ] }, "example": [ "read", "write" ] } } }, "Registrar": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer", "example": 42 }, "nichandle": { "type": "string", "example": "REGISTRAR-NIC" }, "name": { "type": "string", "description": "Registrar name", "example": "Example Registrar SAM" } } }, { "$ref": "#/components/schemas/RegistrarFields" }, { "type": "object", "properties": { "pending_changes": { "allOf": [ { "$ref": "#/components/schemas/RegistrarFields" } ], "description": "Requested values awaiting validation" } } } ] }, "RegistrarFields": { "type": "object", "properties": { "address1": { "type": "string", "example": "1 boulevard Princesse Charlotte" }, "address2": { "type": "string" }, "postal_code": { "type": "string", "example": "98000" }, "city": { "type": "string", "example": "Monaco" }, "country": { "type": "string", "description": "ISO country code", "example": "MC" }, "phone": { "type": "string", "example": "+377 93 00 00 00" }, "phone2": { "type": "string" }, "email": { "type": "string", "format": "email" }, "billing_email": { "type": "string", "format": "email" }, "directory_listed": { "type": "boolean", "description": "Listed in the public registrar directory" }, "auto_renew_default": { "type": "boolean", "description": "Automatic renewal by default for new domains" }, "website": { "type": "string" }, "public_name": { "type": "string" }, "public_phone": { "type": "string" }, "public_email": { "type": "string", "format": "email" } } }, "RegistrarUpdate": { "allOf": [ { "$ref": "#/components/schemas/RegistrarFields" } ], "description": "Fields to change (at least one). address1, postal_code, city, email and phone cannot be emptied." }, "DomainStatus": { "type": "string", "enum": [ "active", "frozen", "blocked", "deleted", "orphan", "expired", "archived" ], "example": "active" }, "DomainCollection": { "type": "object", "properties": { "count": { "type": "integer" }, "domains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1234 }, "domain": { "type": "string", "example": "example.mc" }, "status": { "$ref": "#/components/schemas/DomainStatus" }, "expires_at": { "type": [ "string", "null" ], "example": "2027-03-14" }, "auto_renew": { "type": "boolean" } } } } } }, "Contacts": { "type": "object", "properties": { "holder": { "type": "string", "description": "Holder nichandle", "example": "DUPO1-MC" }, "admin": { "type": "string", "description": "Administrative contact nichandle", "example": "DUPO1-MC" }, "tech": { "type": "string", "description": "Technical contact nichandle", "example": "TECH3-MC" } } }, "Dnssec": { "type": [ "object", "null" ], "properties": { "keytag": { "type": "string", "example": "12345" }, "algorithm": { "type": "string", "example": "13" }, "digest_type": { "type": "string", "example": "2" }, "key_digest": { "type": "string", "example": "3F1A…" } } }, "Nameservers": { "type": "array", "minItems": 2, "maxItems": 8, "items": { "type": "string", "example": "ns1.host.mc" } }, "DomainDetail": { "type": "object", "properties": { "id": { "type": "integer" }, "domain": { "type": "string", "example": "example.mc" }, "status": { "$ref": "#/components/schemas/DomainStatus" }, "registered_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "auto_renew": { "type": "boolean" }, "contacts": { "$ref": "#/components/schemas/Contacts" }, "nameservers": { "$ref": "#/components/schemas/Nameservers" }, "dnssec": { "$ref": "#/components/schemas/Dnssec" }, "transfer_pending": { "type": "boolean", "description": "Outbound transfer in progress" }, "pending_changes": { "type": "object", "description": "Requested values awaiting validation, submitted by your registrar (keys: auto_renew, holder, admin, tech, nameservers, dnssec.*, expires_at, status…)", "additionalProperties": true }, "effective": { "type": "object", "description": "State that will apply if the pending requests are approved", "properties": { "auto_renew": { "type": "boolean" }, "contacts": { "$ref": "#/components/schemas/Contacts" }, "nameservers": { "$ref": "#/components/schemas/Nameservers" }, "dnssec": { "$ref": "#/components/schemas/Dnssec" } } } } }, "DomainCheck": { "type": "object", "properties": { "domain": { "type": "string" }, "available": { "type": "boolean" }, "reason": { "type": [ "string", "null" ], "enum": [ "invalid_extension", "invalid_syntax", "already_registered", "reserved", "bsa_blocked", "request_pending", null ] } } }, "DomainCreate": { "type": "object", "required": [ "domain", "contacts", "nameservers" ], "properties": { "domain": { "type": "string", "description": "Full .mc name", "example": "new-name.mc" }, "auto_renew": { "type": "boolean", "description": "Defaults to the registrar setting" }, "contacts": { "allOf": [ { "$ref": "#/components/schemas/Contacts" } ], "required": [ "holder", "admin", "tech" ] }, "nameservers": { "$ref": "#/components/schemas/Nameservers" }, "dnssec": { "$ref": "#/components/schemas/Dnssec" } } }, "DomainUpdate": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "example.mc" }, "auto_renew": { "type": "boolean" }, "contacts": { "allOf": [ { "$ref": "#/components/schemas/Contacts" } ], "description": "Roles to change only" }, "nameservers": { "$ref": "#/components/schemas/Nameservers" }, "dnssec": { "allOf": [ { "$ref": "#/components/schemas/Dnssec" } ], "description": "null to remove DNSSEC" } } }, "DomainTransfer": { "type": "object", "required": [ "domain", "auth_code", "contacts", "nameservers" ], "properties": { "domain": { "type": "string", "example": "example.mc" }, "auth_code": { "type": "string", "description": "Code provided by the losing registrar" }, "contacts": { "allOf": [ { "$ref": "#/components/schemas/Contacts" } ], "required": [ "holder", "admin", "tech" ] }, "nameservers": { "$ref": "#/components/schemas/Nameservers" } } }, "AuthCode": { "type": "object", "properties": { "auth_code": { "type": "string", "example": "48213907561234098765" }, "expires_at": { "type": "string", "example": "2026-10-02 14:30:00" } } }, "ContactFields": { "type": "object", "properties": { "company": { "type": "string", "description": "Company (or last_name required)" }, "last_name": { "type": "string" }, "first_name": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string", "description": "ISO country code", "example": "MC" }, "phone": { "type": "string", "description": "Email or phone required" }, "phone2": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "Contact": { "allOf": [ { "type": "object", "properties": { "nichandle": { "type": "string", "example": "DUPO1-MC" } } }, { "$ref": "#/components/schemas/ContactFields" } ] }, "ContactCollection": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total (all pages)" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "contacts": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Contact" }, { "type": "object", "properties": { "domain_count": { "type": "integer" } } } ] } } } }, "ContactDetail": { "allOf": [ { "$ref": "#/components/schemas/Contact" }, { "type": "object", "properties": { "pending_changes": { "allOf": [ { "$ref": "#/components/schemas/ContactFields" } ], "description": "Values requested by your registrar, awaiting validation" }, "domains": { "type": "array", "description": "Your registrar's domains where the contact is used", "items": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.mc" }, "role": { "type": "string", "enum": [ "holder", "admin", "tech", "other" ] } } } } } } ] }, "ContactCreate": { "allOf": [ { "$ref": "#/components/schemas/ContactFields" } ], "required": [ "address1", "postal_code", "city", "country" ] }, "ContactUpdate": { "type": "object", "required": [ "nichandle" ], "properties": { "nichandle": { "type": "string", "example": "DUPO1-MC" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "phone": { "type": "string" }, "phone2": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "RequestCreated": { "type": "object", "properties": { "request_id": { "type": "integer", "description": "Request number", "example": 260930004 }, "status": { "type": "string", "enum": [ "pending" ], "example": "pending" } } }, "RequestSummary": { "type": "object", "properties": { "id": { "type": "integer", "example": 260930004 }, "type": { "type": "string", "enum": [ "creation", "modification", "deletion", "transfer", "renewal", "reactivation" ] }, "object": { "type": "string", "enum": [ "domain", "contact", "registrar" ] }, "subject": { "type": [ "string", "null" ], "description": "Domain name or nichandle concerned", "example": "new-name.mc" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "submitted_at": { "type": "string", "example": "2026-09-30 10:12:44" }, "processed_at": { "type": [ "string", "null" ] }, "submitted_by": { "type": [ "string", "null" ], "description": "User who submitted the request" } } }, "RequestCollection": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "requests": { "type": "array", "items": { "$ref": "#/components/schemas/RequestSummary" } } } }, "RequestDetail": { "allOf": [ { "$ref": "#/components/schemas/RequestSummary" }, { "type": "object", "properties": { "changes": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "example": "DNS1" }, "old": { "type": [ "string", "null" ] }, "new": { "type": [ "string", "null" ] } } } } } } ] }, "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "too_many_requests", "unavailable", "server_error" ] }, "message": { "type": "string", "description": "Human-readable detail (in French)" }, "details": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Errors per field (422)" } } } } } }