Spaceship Domain Availability API

openapi: 3.0.0
info:
  title: Spaceship.com Async Operations Domain Availability API
  contact:
    email: support@spaceship.com
    url: https://www.spaceship.com/about/contact-us/
  description: "# Spaceship API\n\n## Authentication\n\nSpaceship API uses a combination of API key and API secret for authentication.\n\n### API key setup\nYou can generate your API key and secret in [API Manager](https://www.spaceship.com/application/api-manager/). Use the \"New API key\" button to set up a new API key and follow the guide to get started.\nAfter the key setup has been successful, it should appear on the API Manager application page.\n\n### API key usage\nAs shown in the example below, API consumers shall pass a valid API key and a corresponding API secret in the X-API-Secret headers.\nYou do not need to encode the API key and the API secret.\n```bash\ncurl -X GET '/api/resource' \\\n-H 'X-Api-Secret: F3brvQluT4s8aDB7PeFBH6qKHfH2xTKTneCjZbq3z2w7rj2vV6n_zhSvvJoQ' \\\n-H 'X-Api-Key: JdIS8QYFMZpVKupJtdc3'\n```\n\n## Asynchronous Operations\n\nSome API operations may take an extended period to complete. For these long-running operations, the API returns an HTTP 202 Accepted response with a `spaceship-async-operationid` header containing a unique operation identifier.\n\n### How Async Operations Work\n\n1. **Initiate Operation**: When you make a request that requires asynchronous processing (e.g., domain registration, transfer operations), the API immediately returns a 202 response.\n\n2. **Receive Operation ID**: The response includes the `spaceship-async-operationid` header with a unique identifier for tracking the operation.\n\n3. **Poll for Status**: Use the operation ID to poll the `/v1/async-operations/{operationId}` endpoint to check the current status of your operation.\n\n4. **Operation States**: Async operations can have the following statuses:\n   - `pending` - The operation is still in progress\n   - `success` - The operation completed successfully\n   - `failed` - The operation encountered an error and could not complete\n\n### Example Workflow\n\n```bash\n# Step 1: Initiate an async operation (e.g., domain registration)\ncurl -X POST '/api/v1/domains/example.com' \\\n-H 'X-Api-Secret: YOUR_SECRET' \\\n-H 'X-Api-Key: YOUR_KEY' \\\n-H 'Content-Type: application/json' \\\n-d '{\n  \"autoRenew\": false,\n  \"years\": 1,\n  \"privacyProtection\": {\n    \"level\": \"high\",\n    \"userConsent\": true\n  },\n  \"contacts\": {\n    \"registrant\": \"CONTACT_ID\",\n    \"admin\": \"CONTACT_ID\",\n    \"tech\": \"CONTACT_ID\",\n    \"billing\": \"CONTACT_ID\"\n  }\n}'\n\n# Response: 202 Accepted\n# Headers: spaceship-async-operationid: abc123xyz\n\n# Step 2: Check operation status\ncurl -X GET '/api/v1/async-operations/abc123xyz' \\\n-H 'X-Api-Secret: YOUR_SECRET' \\\n-H 'X-Api-Key: YOUR_KEY'\n\n# Response includes:\n# - status: \"pending\" | \"success\" | \"failed\"\n# - type: Operation type (e.g., \"domains_Create\")\n# - details: Additional information about the operation\n# - createdAt: Timestamp when operation was created\n# - modifiedAt: Timestamp of last status update\n```\n\n### Permissions \n\n - <b id=\"scopes/domains:read\">domains:read</b> - Read domain information and check configuration\n- <b id=\"scopes/domains:write\">domains:write</b> - Manage domains and domain settings\n- <b id=\"scopes/domains:transfer\">domains:transfer</b> - Transfer domains in and out\n- <b id=\"scopes/domains:billing\">domains:billing</b> - Manage domains billing operations\n- <b id=\"scopes/contacts:write\">contacts:write</b> - Save contact details\n- <b id=\"scopes/contacts:read\">contacts:read</b> - Read contact details\n- <b id=\"scopes/dnsrecords:write\">dnsrecords:write</b> - Write DNS resource records\n- <b id=\"scopes/dnsrecords:read\">dnsrecords:read</b> - Read DNS resource records\n- <b id=\"scopes/asyncoperations:read\">asyncoperations:read</b> - Read async operations details\n- <b id=\"scopes/sellerhub:read\">sellerhub:read</b> - Read SellerHub Domains\n- <b id=\"scopes/sellerhub:write\">sellerhub:write</b> - Write SellerHub Domains"
  version: 1.0.0
  x-logo:
    url: https://spaceship-cdn.com/spaceship-api-doc-assets/logo.svg
servers:
- url: https://spaceship.dev/api
  description: The main server for the Spaceship External API
  variables: {}
security:
- apiKey: []
  apiSecret: []
tags:
- name: Domain Availability
paths:
  /v1/domains/available:
    post:
      operationId: checkDomainsAvailability
      summary: Check domains availability
      description: "Check domains availability.\n\n### Required Permissions \n\n - <a href=\"#scopes/domains:read\">domains:read</a>\n\n### Rate Limits \n\n * The limit to check domains availability is 30 requests per user, within 30 seconds."
      parameters: []
      responses:
        '200':
          description: The request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domains.GetDomainsAvailabilityResult'
        '400':
          description: The request is invalid.
          headers:
            spaceship-error-code:
              required: true
              schema:
                $ref: '#/components/schemas/errorCode'
            spaceship-operation-id:
              required: true
              schema:
                $ref: '#/components/schemas/operationId'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '401':
          description: The user's request was not authorized properly.
          headers:
            spaceship-error-code:
              required: true
              schema:
                $ref: '#/components/schemas/errorCode'
            spaceship-operation-id:
              required: true
              schema:
                $ref: '#/components/schemas/operationId'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: The user's request not allowed to perform this action with the current scopes.
          headers:
            spaceship-error-code:
              required: true
              schema:
                $ref: '#/components/schemas/errorCode'
            spaceship-operation-id:
              required: true
              schema:
                $ref: '#/components/schemas/operationId'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: The requested object was not found.
          headers:
            spaceship-error-code:
              required: true
              schema:
                $ref: '#/components/schemas/errorCode'
            spaceship-operation-id:
              required: true
              schema:
                $ref: '#/components/schemas/operationId'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ObjectNotFoundError'
        '422':
          description: The entity is unprocessable.
          headers:
            spaceship-error-code:
              required: true
              schema:
                $ref: '#/components/schemas/errorCode'
            spaceship-operation-id:
              required: true
              schema:
                $ref: '#/components/schemas/operationId'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '429':
          description: The response indicates that the rate limit for the API has been exceeded. It includes details about the rate limit, like the number of requests left and the time the rate limit window resets.
          headers:
            spaceship-error-code:
              required: true
              schema:
                $ref: '#/components/schemas/errorCode'
            spaceship-operation-id:
              required: true
              schema:
                $ref: '#/components/schemas/operationId'
            X-RateLimit-Limit:
              required: true
              description: Request limit per the allotted time window
              schema:
                type: integer
                format: int32
                minimum: 1
                maximum: 2147483647
            X-RateLimit-Remaining:
              required: true
              description: The number of requests left for the time window
              schema:
                type: integer
                format: int32
                minimum: 0
                maximum: 2147483647
            X-RateLimit-Reset:
              required: true
              description: The UTC date/time when the current rate limit window resets
              schema:
                type: integer
                format: int32
                minimum: 1
                maximum: 2147483647
            Retry-After:
              required: true
              description: The number of seconds inndicating how long the client ought to wait before making a follow-up request
              schema:
                type: integer
                format: int32
                minimum: 1
                maximum: 2147483647
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: The infrastructure encountered an error.
          headers:
            spaceship-error-code:
              required: true
              schema:
                $ref: '#/components/schemas/errorCode'
            spaceship-operation-id:
              required: true
              schema:
                $ref: '#/components/schemas/operationId'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnexpectedError'
      tags:
      - Domain Availability
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Domains.GetDomainsAvailabilityRequest'
      x-scopes:
      - domains:read
      x-codeSamples:
      - lang: javascript
        source: "const url = 'https://spaceship.dev/api/v1/domains/available';\nconst options = {\n  method: 'POST',\n  headers: {\n    'X-API-Key': 'REPLACE_KEY_VALUE',\n    'X-API-Secret': 'REPLACE_KEY_VALUE',\n    'content-type': 'application/json'\n  },\n  body: JSON.stringify({domains: ['spaceship.dev']})\n};\n\nfetch(url, options)\n  .then(res => res.json())\n  .then(json => console.log(json))\n  .catch(err => console.error(err));"
      - lang: php
        source: "<?php\nrequire_once('vendor/autoload.php');\n\n$client = new \\GuzzleHttp\\Client();\n\n$response = $client->request('POST', 'https://spaceship.dev/api/v1/domains/available', [\n  'body' => '{\"domains\":[\"spaceship.dev\"]}',\n  'headers' => [\n    'X-API-Key' => 'REPLACE_KEY_VALUE',\n    'X-API-Secret' => 'REPLACE_KEY_VALUE',\n    'content-type' => 'application/json',\n  ],\n]);\n\necho $response->getBody();"
      - lang: python
        source: "import requests\n\nurl = \"https://spaceship.dev/api/v1/domains/available\"\n\npayload = { \"domains\": [\"spaceship.dev\"] }\nheaders = {\n    \"X-API-Key\": \"REPLACE_KEY_VALUE\",\n    \"X-API-Secret\": \"REPLACE_KEY_VALUE\",\n    \"content-type\": \"application/json\"\n}\n\nresponse = requests.post(url, json=payload, headers=headers)\n\nprint(response.text)"
      - lang: shell
        source: "curl --request POST \\\n     --url https://spaceship.dev/api/v1/domains/available \\\n     --header 'X-API-Key: REPLACE_KEY_VALUE' \\\n     --header 'X-API-Secret: REPLACE_KEY_VALUE' \\\n     --header 'content-type: application/json' \\\n     --data '\n{\n  \"domains\": [\n    \"spaceship.dev\"\n  ]\n}\n'"
  /v1/domains/{domain}/available:
    get:
      operationId: checkSingleDomainAvailability
      summary: Check single domain availability
      description: "Check single domain availability.\n\n### Required Permissions \n\n - <a href=\"#scopes/domains:read\">domains:read</a>\n\n### Rate Limits \n\n * The limit to check domain availability is 5 requests per domain, within 300 seconds.\n* The limit to check domain availability is 30 requests per user, within 30 seconds."
      parameters:
      - name: domain
        in: path
        required: true
        description: Domain name in ASCII format (A-label) whose details are to be fetched. The domain name must be provided in a fully qualified domain format.
        schema:
          type: string
          example: spaceship.com
          minLength: 4
          maxLength: 255
          format: domain
          description: Domain name in UTF-8 or ASCII format (U-label or A-label)
      responses:
        '200':
          description: The request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainAvailabilityResult'
        '400':
          description: The request is invalid.
          headers:
            spaceship-error-code:
              required: true
              schema:
                $ref: '#/components/schemas/errorCode'
            spaceship-operation-id:
              required: true
              schema:
                $ref: '#/components/schemas/operationId'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '401':
          description: The user's request was not authorized properly.
          headers:
            spaceship-error-code:
              required: true
              schema:
                $ref: '#/components/schemas/errorCode'
            spaceship-operation-id:
              required: true
              schema:
                $ref: '#/components/schemas/operationId'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: The user's request not allowed to perform this action with the current scopes.
          headers:
            spaceship-error-code:
              required: true
              schema:
                $ref: '#/components/schemas/errorCode'
            spaceship-operation-id:
              required: true
              schema:
                $ref: '#/components/schemas/operationId'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: The requested object was not found.
          headers:
            spaceship-error-code:
              required: true
              schema:
                $ref: '#/components/schemas/errorCode'
            spaceship-operation-id:
              required: true
              schema:
                $ref: '#/components/schemas/operationId'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ObjectNotFoundError'
        '422':
          description: The entity is unprocessable.
          headers:
            spaceship-error-code:
              required: true
              schema:
                $ref: '#/components/schemas/errorCode'
            spaceship-operation-id:
              required: true
              schema:
                $ref: '#/components/schemas/operationId'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '429':
          description: The response indicates that the rate limit for the API has been exceeded. It includes details about the rate limit, like the number of requests left and the time the rate limit window resets.
          headers:
            spaceship-error-code:
              required: true
              schema:
                $ref: '#/components/schemas/errorCode'
            spaceship-operation-id:
              required: true
              schema:
                $ref: '#/components/schemas/operationId'
            X-RateLimit-Limit:
              required: true
              description: Request limit per the allotted time window
              schema:
                type: integer
                format: int32
                minimum: 1
                maximum: 2147483647
            X-RateLimit-Remaining:
              required: true
              description: The number of requests left for the time window
              schema:
                type: integer
                format: int32
                minimum: 0
                maximum: 2147483647
            X-RateLimit-Reset:
              required: true
              description: The UTC date/time when the current rate limit window resets
              schema:
                type: integer
                format: int32
                minimum: 1
                maximum: 2147483647
            Retry-After:
              required: true
              description: The number of seconds inndicating how long the client ought to wait before making a follow-up request
              schema:
                type: integer
                format: int32
                minimum: 1
                maximum: 2147483647
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: The infrastructure encountered an error.
          headers:
            spaceship-error-code:
              required: true
              schema:
                $ref: '#/components/schemas/errorCode'
            spaceship-operation-id:
              required: true
              schema:
                $ref: '#/components/schemas/operationId'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnexpectedError'
      tags:
      - Domain Availability
      x-scopes:
      - domains:read
      x-codeSamples:
      - lang: javascript
        source: "const url = 'https://spaceship.dev/api/v1/domains/spaceship.com/available';\nconst options = {\n  method: 'GET',\n  headers: {'X-API-Key': 'REPLACE_KEY_VALUE', 'X-API-Secret': 'REPLACE_KEY_VALUE'}\n};\n\nfetch(url, options)\n  .then(res => res.json())\n  .then(json => console.log(json))\n  .catch(err => console.error(err));"
      - lang: php
        source: "<?php\nrequire_once('vendor/autoload.php');\n\n$client = new \\GuzzleHttp\\Client();\n\n$response = $client->request('GET', 'https://spaceship.dev/api/v1/domains/spaceship.com/available', [\n  'headers' => [\n    'X-API-Key' => 'REPLACE_KEY_VALUE',\n    'X-API-Secret' => 'REPLACE_KEY_VALUE',\n  ],\n]);\n\necho $response->getBody();"
      - lang: python
        source: "import requests\n\nurl = \"https://spaceship.dev/api/v1/domains/spaceship.com/available\"\n\nheaders = {\n    \"X-API-Key\": \"REPLACE_KEY_VALUE\",\n    \"X-API-Secret\": \"REPLACE_KEY_VALUE\"\n}\n\nresponse = requests.get(url, headers=headers)\n\nprint(response.text)"
      - lang: shell
        source: "curl --request GET \\\n     --url https://spaceship.dev/api/v1/domains/spaceship.com/available \\\n     --header 'X-API-Key: REPLACE_KEY_VALUE' \\\n     --header 'X-API-Secret: REPLACE_KEY_VALUE'"
components:
  schemas:
    DomainAvailabilityResult:
      type: object
      required:
      - domain
      - result
      - premiumPricing
      properties:
        domain:
          allOf:
          - $ref: '#/components/schemas/domainName'
          example: spaceship.dev
          readOnly: true
        result:
          allOf:
          - $ref: '#/components/schemas/DomainAvailabilityStatus'
          readOnly: true
        premiumPricing:
          type: array
          items:
            $ref: '#/components/schemas/DomainPriceDetails'
          readOnly: true
      description: Domain availability check result
    DomainAvailabilityStatus:
      type: string
      enum:
      - available
      - taken
      - invalidDomainName
      - tldNotSupported
      - unexpectedError
      example: available
      description: 'Domain availability status. Possible values include:

        * `available` - The domain is available for registration.

        * `taken` - Domain is already taken and available for transfer.

        * `invalidDomainName` - Domain name is invalid.

        * `tldNotSupported` - Specified TLD is not supported.

        * `unexpectedError` - An error occurred while checking domain availability. The system was unable to determine the domain''s status due to a technical issue.'
    Domains.GetDomainsAvailabilityRequest:
      type: object
      required:
      - domains
      properties:
        domains:
          type: array
          items:
            $ref: '#/components/schemas/domainName'
          example:
          - spaceship.dev
          minItems: 1
          maxItems: 20
          description: List of domain names in ASCII format (A-label) whose details are to be fetched. The domain name must be provided in a fully qualified domain format.
      description: Domains availability check request
    operationId:
      type: string
      maxLength: 16
      pattern: ^[a-z0-9]{16}$
      description: 16-characters unique identifier of the operation
    RateLimitError:
      type: object
      required:
      - detail
      properties:
        detail:
          type: string
          pattern: ^[\s|\S]*$
          description: A general message about the exception
          readOnly: true
    Domains.GetDomainsAvailabilityResult:
      type: object
      required:
      - domains
      properties:
        domains:
          type: array
          items:
            $ref: '#/components/schemas/DomainAvailabilityResult'
          readOnly: true
      description: Domains availability check result
    ForbiddenError:
      type: object
      required:
      - detail
      properties:
        detail:
          type: string
          pattern: ^[\s|\S]*$
          description: A general message about the exception
          readOnly: true
    Currency:
      type: string
      example: USD
      minLength: 3
      maxLength: 3
      pattern: ^USD$
      description: Currency code following ISO 4217 standard. Currently only USD is supported.
    ValidationError:
      type: object
      required:
      - detail
      - data
      properties:
        detail:
          type: string
          pattern: ^[\s|\S]*$
          description: A general message about the exception
          readOnly: true
        data:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                example: name
                pattern: ^[\s|\S]*$
                description: The path to the field that caused the validation error
                readOnly: true
              details:
                type: string
                example: The domain name contains invalid characters
                pattern: ^[\s|\S]*$
                description: A specific message about what is wrong with the field
                readOnly: true
            required:
            - field
            - details
          description: A detailed list of validation errors
          readOnly: true
    ObjectNotFoundError:
      type: object
      required:
      - detail
      properties:
        detail:
          type: string
          pattern: ^[\s|\S]*$
          description: A general message about the exception
          readOnly: true
    DomainPriceDetails:
      type: object
      required:
      - operation
      - price
      - currency
      properties:
        operation:
          type: string
          enum:
          - register
          - transfer
          - renew
          - restore
          example: register
          description: Operation to which a premium price is applied
        price:
          type: number
          format: decimal
          example: 10.99
          description: Premium price amount
        currency:
          allOf:
          - $ref: '#/components/schemas/Currency'
          description: Premium price currency
      description: Domain premium prices
    domainName:
      type: string
      example: spaceship.com
      minLength: 4
      maxLength: 255
      format: domain
      description: Domain name in UTF-8 or ASCII format (U-label or A-label)
    ErrorDetail:
      type: object
      required:
      - detail
      properties:
        detail:
          type: string
          pattern: ^[\s|\S]*$
          description: A general message about the exception
          readOnly: true
    errorCode:
      type: string
      maxLength: 255
      pattern: ^(business|application|infrastructure)(\.[a-zA-Z]+)+$
      description: The dot-separated error code indicating the type of the problem occurred
    UnauthorizedError:
      type: object
      required:
      - detail
      properties:
        detail:
          type: string
          pattern: ^[\s|\S]*$
          description: A general message about the exception
          readOnly: true
    UnexpectedError:
      type: object
      required:
      - detail
      properties:
        detail:
          type: string
          pattern: ^[\s|\S]*$
          description: A general message about the exception
          readOnly: true
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authenticating requests, with a set of scopes (permissions) defined by the user at the time of creation.
    apiSecret:
      type: apiKey
      in: header
      name: X-API-Secret
      description: API secret for authenticating requests must be set together with the API key.
x-scopes:
  domains:read: Read domain information and check configuration
  domains:write: Manage domains and domain settings
  domains:transfer: Transfer domains in and out
  domains:billing: Manage domains billing operations
  contacts:write: Save contact details
  contacts:read: Read contact details
  dnsrecords:write: Write DNS resource records
  dnsrecords:read: Read DNS resource records
  asyncoperations:read: Read async operations details
  sellerhub:read: Read SellerHub Domains
  sellerhub:write: Write SellerHub Domains
x-tagGroups:
- name: Domains
  tags:
  - Domain Management
  - Domain Availability
  - Domain Settings
  - Personal Nameservers
  - Domain Transfer
- name: Contacts
  tags:
  - Contacts
  - Contacts attributes
- name: DNS
  tags:
  - DNS records
- name: SellerHub
  tags:
  - SellerHub
- name: Async Operations
  tags:
  - Async Operations