Nerdit Link API

Reserved /api/link product boundary.

GitHub OpenAPI

Operations 6

POST /api/link/claim Exchange a link code for a node identity #
POST /api/link/device Request a device link code a human can approve in the console #
POST /api/link/device/poll Ask whether a device link request has been answered yet #
POST /api/link/preauth Enroll a machine with a pre-authorized link key #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/nerdit-ai:nerdit-ai-link-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

nerdit-ai-link-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Nerdit Cloud (web) Link API
  version: 0.1.0
  description: Reserved /api/link product boundary.
tags:
- name: Link
  description: Reserved /api/link product boundary.
paths:
  /api/link:
    get:
      tags:
      - Link
      summary: Link Boundary
      operationId: link_boundary_api_link_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /api/link/metadata:
    get:
      tags:
      - Link
      summary: Hosted-share metadata a daemon reads on `nerdit link refresh`
      description: 'Publish the hosted base domain. Unauthenticated, static, cacheable.


        No session, no node, no rate limiter of its own: the answer is the same

        for every caller and is already public in DNS and in the wildcard

        certificate, so there is nothing here for a caller to be authorized

        *for*. A pre-P26 daemon never asks; a pre-P26 **cloud** answers 404,

        which the daemon maps to its own ``link.refresh_unsupported`` — so the

        one thing this route must never do is exist and answer something else.'
      operationId: metadata_api_link_metadata_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkMetadataView'
  /api/link/claim:
    post:
      tags:
      - Link
      summary: Exchange a link code for a node identity
      description: Release the node identity a link code names, at most once per code.
      operationId: claim_api_link_claim_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkClaimRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkClaimResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/link/device:
    post:
      tags:
      - Link
      summary: Request a device link code a human can approve in the console
      description: 'Mint the two artifacts of one device request (D-X16-O1/O3/O5).


        Unauthenticated by design — nobody is signed in on the machine being

        linked, which is the whole point — so this grants nothing on its own. It

        writes one ``pending`` row that names no node and no account: the node

        does not exist until a human approves, and the approval runs the same

        account-standing assertion the console mint runs (D-X16-O25). The most

        this route can be made to produce in bulk is rows that expire, which is

        what the budgets above bound.


        Both plaintexts exist only in the response object. The row keeps their

        digests; the audit row keeps neither, and passes both to

        ``forbidden_values`` so that any future edit which interpolates one into

        the metadata raises here rather than shipping.


        Two other things are captured, and the difference between them is the

        whole of D-X16-O23. The three strings the daemon *reports* about itself

        are stored because the approval screen has to show a human something

        they can recognise their own laptop by — bounded and control-stripped on

        the way in, and labelled unverified on the way out, because this route

        is unauthenticated and a phisher writes whatever reads best. The address

        the request came *from* is stored because it is the one requester fact

        the requester cannot choose, and because it can only be observed here:

        by the time the approval screen loads, the only address the cloud can

        see is the approver''s own.'
      operationId: request_device_link_api_link_device_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceLinkRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceLinkResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/link/device/poll:
    post:
      tags:
      - Link
      summary: Ask whether a device link request has been answered yet
      description: 'Wait for a human, then release the same identity ``/claim`` releases.


        The 200 body is constructed from :class:`LinkClaimResponse` itself, so

        an approved device link and an ``NL-`` claim are the same bytes on the

        wire and a daemon parses one thing (D-X16-O2).


        Ordering is the security of this route. The rate limit is charged first

        because it is the only control that exists before the caller has said

        anything. The cadence check comes next and answers ``slow_down`` without

        touching the database — identically for a real code and an invented one,

        so it tells a fast prober nothing. Only then does the policy layer look

        the row up, and its own first move is the constant-time comparison

        against the pinned credential (D-X16-O22): every answer that reveals

        state sits behind it.'
      operationId: poll_device_link_api_link_device_poll_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DevicePollRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkClaimResponse'
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DevicePollPending'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/link/preauth:
    post:
      tags:
      - Link
      summary: Enroll a machine with a pre-authorized link key
      description: 'Turn a key and a credential into the node identity the machine comes up as.


        The response model is the claim route''s own (D-X16-O7): a daemon that

        can read one answer can read the other, and the shape being *the same

        class* rather than a copy is what keeps it that way.


        Everything that decides anything is in

        :func:`~nerdit_cloud.nodes.preauth.consume_preauth_key`, including the

        D-X16-O9 evaluation order this route must not second-guess. What is

        here is the metering, the shape check that makes passing the plaintext

        to ``forbidden_values`` safe, and the commit-then-raise the refusal path

        shares with every other route in this codebase.'
      operationId: enroll_api_link_preauth_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreauthLinkRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkClaimResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ErrorDetail:
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          title: Message
        status:
          type: integer
          title: Status
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
        details:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Details
      additionalProperties: false
      type: object
      required:
      - code
      - message
      - status
      title: ErrorDetail
      description: The stable body nested under the envelope's ``error`` key.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LinkMetadataView:
      properties:
        nodes_base_domain:
          type: string
          title: Nodes Base Domain
      additionalProperties: false
      type: object
      required:
      - nodes_base_domain
      title: LinkMetadataView
      description: 'What a linked daemon re-reads to learn this deployment''s hosted suffix.


        Deliberately one field. It is the *refresh* half of the claim response

        (``nerdit link refresh`` → ``POST /link/refresh`` on the daemon), for the

        node that linked before P26 or whose cloud moved its wildcard, and adding

        anything account-shaped to it would make an unauthenticated route answer a

        question about somebody — which is why the hosted entitlement bit is

        **not** here (D-HC-6 defers that to ADR-HC-2).'
    ErrorCode:
      type: string
      enum:
      - bad_request
      - unauthorized
      - forbidden
      - not_found
      - method_not_allowed
      - conflict
      - validation_failed
      - rate_limited
      - internal_error
      - service_unavailable
      - not_implemented
      - plan_limit_exceeded
      - link_code_invalid
      - link_code_expired
      - link_code_consumed
      - link_code_attempts_exceeded
      - link_code_limit_exceeded
      - link_code_denied
      - link_key_invalid
      - preauth_key_limit_exceeded
      - node_not_found
      - node_already_linked
      - node_offline
      - machine_waking
      - node_revoked
      - entitlement_required
      - organisation_has_members
      - trial_quota_used
      - trial_boxes_busy
      - trial_archived
      - replace.bad_url
      - replace.extractor_unavailable
      - replace.already_claimed
      - csrf_failed
      - auth_transaction_invalid
      - auth_transaction_expired
      - auth_identity_invalid
      - auth_identity_deleting
      - session_invalid
      - session_expired
      - navigation_ticket_invalid
      - navigation_ticket_expired
      - navigation_ticket_consumed
      - proxy_session_invalid
      - proxy_session_expired
      - origin_forbidden
      - hosted_private
      - hosted_disabled
      - visitor_session_required
      - custom_domains.pro_required
      - custom_domains.limit_reached
      - custom_domains.apex_unsupported
      - custom_domains.taken
      - custom_domains.not_found
      - access_revoked
      - webhook_signature_invalid
      - already_subscribed
      - billing_account_missing
      - oauth_invalid_request
      - oauth_invalid_client
      - oauth_invalid_grant
      - oauth_unsupported_grant_type
      - oauth_invalid_scope
      - oauth_access_denied
      - oauth_server_error
      - oauth_temporarily_unavailable
      - oauth_invalid_token
      - oauth_insufficient_scope
      - protocol_version_unsupported
      - node_authentication_failed
      - relay_frame_invalid
      - relay_destination_invalid
      - relay_stream_unknown
      - relay_stream_limit_exceeded
      - relay_body_too_large
      - relay_response_too_large
      - relay_bandwidth_exceeded
      - relay_backpressure
      - relay_draining
      - relay_stream_timeout
      title: ErrorCode
      description: Codes clients may branch on independently of human-readable messages.
    DeviceLinkRequest:
      properties:
        credential_reference:
          type: string
          maxLength: 255
          minLength: 1
          title: Credential Reference
        hostname_hint:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Hostname Hint
        daemon_version:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Daemon Version
        os:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Os
      additionalProperties: false
      type: object
      required:
      - credential_reference
      title: DeviceLinkRequest
      description: 'What a daemon says about itself when it asks to be linked.


        Only ``credential_reference`` is load-bearing: it is pinned to the row here

        and every later step — the fingerprint the console renders, the node the

        approval adopts, the poll''s constant-time comparison — is bound to *that*

        value (D-X16-O22), never to whatever presents itself later.


        The other three are display strings and are treated as hostile

        (D-X16-O23). They are bounded above; nothing downstream may render them

        without saying, in the copy, that the requesting machine reported them and

        nobody verified them.'
    DevicePollRequest:
      properties:
        device_code:
          type: string
          maxLength: 128
          minLength: 1
          title: Device Code
        credential_reference:
          type: string
          maxLength: 255
          minLength: 1
          title: Credential Reference
      additionalProperties: false
      type: object
      required:
      - device_code
      - credential_reference
      title: DevicePollRequest
      description: 'A daemon asking whether a human has answered yet.


        The credential travels on every poll because the comparison against the

        row''s pinned value is the *first* thing the policy layer does with the row

        (D-X16-O22): everything after it reveals state — approved, denied, expired —

        and a caller who cannot present the credential the request was minted with

        has no business learning any of it.'
    PreauthLinkRequest:
      properties:
        key:
          type: string
          maxLength: 43
          minLength: 1
          title: Key
        credential_reference:
          type: string
          maxLength: 255
          minLength: 1
          title: Credential Reference
        hostname_hint:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Hostname Hint
      additionalProperties: false
      type: object
      required:
      - key
      - credential_reference
      title: PreauthLinkRequest
      description: 'What a machine sends to enroll itself (D-X16-O7 payload shape).


        Two load-bearing fields and one display string. The key authorises; the

        credential is what gets enrolled and is the value D-X16-O9''s idempotency is

        keyed on. ``hostname_hint`` is the stem of the slug and the node''s initial

        display name — this route is unauthenticated, so it is attacker-chosen text

        (D-X16-O23), bounded here and normalised before it is written.'
    LinkClaimRequest:
      properties:
        code:
          type: string
          maxLength: 128
          minLength: 1
          title: Code
        credential_reference:
          type: string
          maxLength: 255
          minLength: 1
          title: Credential Reference
      additionalProperties: false
      type: object
      required:
      - code
      - credential_reference
      title: LinkClaimRequest
      description: The daemon presents the plaintext code exactly once.
    DevicePollPending:
      properties:
        status:
          type: string
          enum:
          - authorization_pending
          - slow_down
          title: Status
        interval:
          type: integer
          title: Interval
      additionalProperties: false
      type: object
      required:
      - status
      - interval
      title: DevicePollPending
      description: 'The 202 body: nobody has answered, and here is when to ask again.


        Two statuses, both RFC 8628''s. ``authorization_pending`` is the honest

        answer to a polite poll; ``slow_down`` is what a daemon polling faster than

        the interval it was given gets instead, with the longer interval it should

        adopt. Neither says anything about the request beyond "not settled", which

        is what keeps a fast-polling stranger from learning that a code exists.'
    LinkClaimResponse:
      properties:
        node_id:
          type: string
          format: uuid
          title: Node Id
        node_slug:
          type: string
          title: Node Slug
        nodes_base_domain:
          type: string
          title: Nodes Base Domain
      additionalProperties: false
      type: object
      required:
      - node_id
      - node_slug
      - nodes_base_domain
      title: LinkClaimResponse
      description: Non-secret node identity; capability material is never issued here.
    DeviceLinkResponse:
      properties:
        device_code:
          type: string
          title: Device Code
        user_code:
          type: string
          title: User Code
        verification_uri:
          type: string
          title: Verification Uri
        verification_uri_complete:
          type: string
          title: Verification Uri Complete
        credential_fingerprint:
          type: string
          title: Credential Fingerprint
        expires_in:
          type: integer
          title: Expires In
        interval:
          type: integer
          title: Interval
      additionalProperties: false
      type: object
      required:
      - device_code
      - user_code
      - verification_uri
      - verification_uri_complete
      - credential_fingerprint
      - expires_in
      - interval
      title: DeviceLinkResponse
      description: 'The two artifacts, where to take one of them, and how long they last.


        ``device_code`` is the daemon''s poll credential and is never displayed;

        ``user_code`` is what the terminal prints for a human to carry. Both leave

        this process exactly once, in this response, and neither is stored: the row

        keeps only ``sha256_hex`` of each (D-X16-O3).


        ``verification_uri_complete`` carries the user code in a **fragment**

        (D-X16-O24), so the one-click link cannot deposit the secret in an access

        log, a CDN log, a ``Referer`` header or a shared-link history the way

        ``?user_code=`` would. ``credential_fingerprint`` is the same eight-hex

        prefix the console will show beside the approval, so an operator standing at

        the terminal can check that the screen is describing *this* machine

        (D-X16-O4 — an aid for the operator who has the terminal, never a defence

        against a phished stranger).'
    ErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      additionalProperties: false
      type: object
      required:
      - error
      title: ErrorEnvelope
      description: Response model used by all cloud API errors.