> ## Documentation Index
> Fetch the complete documentation index at: https://nemonist.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a private endpoint

> Creates a custom endpoint as a draft. Drafts are not routed: validate one with POST /private-endpoints/{id}/validate, then activate it. Pass activate to do all three in one call; if validation fails the draft is kept and answered with 422 and its checks. Send an Idempotency-Key header to make retries safe: the same key and body return the first endpoint; the same key with another body answers 422 idempotency_key_reused. Management key required.



## OpenAPI

````yaml /openapi.json post /private-endpoints
openapi: 3.1.0
info:
  title: Nemonist API
  version: 1.0.0
  description: >-
    OpenRouter-compatible API with durable per-workspace memory. Point any
    OpenRouter client at https://nemonist.com/api/v1 with a Nemonist key
    (sk-nm-...). Chat completions, Responses and Messages requests from a
    workspace carrying a .nemonist/key get its memory; every other request is
    answered as OpenRouter would.
  contact:
    name: Nemonist
    url: https://nemonist.com
servers:
  - url: https://nemonist.com/api/v1
    description: Production
security:
  - apiKey: []
tags:
  - description: API key management endpoints
    name: API Keys
  - description: Analytics and usage endpoints
    name: Analytics
  - description: Anthropic Messages endpoints
    name: Anthropic Messages
  - description: BYOK endpoints
    name: BYOK
  - description: Benchmarks endpoints
    name: Benchmarks
  - description: Chat completion endpoints
    name: Chat
  - description: Credit management endpoints
    name: Credits
  - description: >-
      Public OpenRouter usage datasets. Data returned by these endpoints is
      licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/):
      reuse and republish it, including commercially, with attribution to
      OpenRouter.
    name: Datasets
  - description: Text embedding endpoints
    name: Embeddings
  - description: Endpoint information
    name: Endpoints
  - name: Folders
    description: >-
      Your memory folders, over your account's API key: read, export, upload,
      and manage keys.
  - description: Generation history endpoints
    name: Generations
  - description: Guardrails endpoints
    name: Guardrails
  - description: Images endpoints
    name: Images
  - name: Memory
    description: Nemonist's per-workspace memory.
  - name: Model runs
    description: Run models (physics and others) on inputs; one contract for every model
  - description: Model information endpoints
    name: Models
  - description: OAuth authentication endpoints
    name: OAuth
  - description: Organization endpoints
    name: Organization
  - description: Private Endpoints endpoints
    name: Private Endpoints
  - description: Provider information endpoints
    name: Providers
  - description: Rerank endpoints
    name: Rerank
  - description: OpenAI-compatible Responses API endpoints
    name: Responses
  - description: Speech-to-text endpoints
    name: STT
    x-displayName: Transcriptions
  - description: >-
      System One endpoints for models such as Jev, compatible with the TypeSafe
      SDKs. See https://openrouter.ai/docs/guides/community/typesafe-sdk.
    name: SystemOne
    x-displayName: System One
  - description: Text-to-speech endpoints
    name: TTS
    x-displayName: Speech
  - description: Video Generation endpoints
    name: Video Generation
  - description: Workspaces endpoints
    name: Workspaces
  - name: beta.responses
    description: >-
      Deprecated alias of responses. Use responses instead; scheduled for
      removal (sunset date TBD).
paths:
  /private-endpoints:
    parameters:
      - $ref: '#/components/parameters/AppIdentifier'
      - $ref: '#/components/parameters/AppDisplayName'
      - $ref: '#/components/parameters/AppCategories'
    post:
      tags:
        - Private Endpoints
      summary: Create a private endpoint
      description: >-
        Creates a custom endpoint as a draft. Drafts are not routed: validate
        one with POST /private-endpoints/{id}/validate, then activate it. Pass
        activate to do all three in one call; if validation fails the draft is
        kept and answered with 422 and its checks. Send an Idempotency-Key
        header to make retries safe: the same key and body return the first
        endpoint; the same key with another body answers 422
        idempotency_key_reused. Management key required.
      operationId: createPrivateEndpoint
      parameters:
        - description: >-
            Retry-safe create: a repeated create with the same key from the same
            organization returns the endpoint the first request created instead
            of creating another. The endpoint is returned as it is now. Reusing
            a key with a different request body (model, provider, base URL,
            upstream model ID, declared ZDR or region, pricing, or declared
            parameters) is rejected with 422 `idempotency_key_reused`. Declared
            parameters are compared as a set, so a retry that reorders or
            repeats a name replays the endpoint. `activate` and `settings` are
            not compared, and later edits to the endpoint do not affect the
            comparison. `settings` is still validated before the replay, so a
            retry with invalid settings returns 400 `settings_invalid` instead
            of the endpoint.
          in: header
          name: idempotency-key
          required: false
          schema:
            description: >-
              Retry-safe create: a repeated create with the same key from the
              same organization returns the endpoint the first request created
              instead of creating another. The endpoint is returned as it is
              now. Reusing a key with a different request body (model, provider,
              base URL, upstream model ID, declared ZDR or region, pricing, or
              declared parameters) is rejected with 422
              `idempotency_key_reused`. Declared parameters are compared as a
              set, so a retry that reorders or repeats a name replays the
              endpoint. `activate` and `settings` are not compared, and later
              edits to the endpoint do not affect the comparison. `settings` is
              still validated before the replay, so a retry with invalid
              settings returns 400 `settings_invalid` instead of the endpoint.
            example: wayfair-gpt-4o-eastus-2026-09
            maxLength: 255
            minLength: 1
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNemonistEndpointRequest'
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                description: >-
                  The created endpoint: a draft, or active when activate was
                  passed.
                properties:
                  data:
                    allOf:
                      - $ref: '#/components/schemas/NemonistEndpoint'
                    description: >-
                      The created endpoint: a draft, or active when activate was
                      passed.
                required:
                  - data
          description: 'The created endpoint: a draft, or active when `activate` was passed'
        '400':
          content:
            application/json:
              example:
                error:
                  code: 400
                  message: Invalid request parameters
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: Bad Request - Invalid request parameters or malformed input
        '401':
          content:
            application/json:
              example:
                error:
                  code: 401
                  message: Missing Authentication header
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized - Authentication required or invalid credentials
        '403':
          content:
            application/json:
              example:
                error:
                  code: 403
                  message: Only management keys can perform this operation
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden - Authentication successful but insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: >-
            The model, provider, or validation workspace was not found. When
            `activate` was passed and the draft was created, `data` carries it
            and any validation checks.
        '408':
          content:
            application/json:
              example:
                error:
                  code: 408
                  message: Operation timed out. Please try again later.
              schema:
                $ref: '#/components/schemas/RequestTimeoutResponse'
          description: Request Timeout - Operation exceeded time limit
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictResponse'
          description: >-
            The request conflicts with the endpoint state, such as a stale
            validation. When `activate` was passed and the draft was created,
            `data` carries it and any validation checks.
        '422':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/CreateNemonistEndpointFailedResponse'
                  - $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: >-
            activate was passed and validation failed: the draft is kept; fix
            it, then call /validate and /activate. Or the Idempotency-Key was
            reused with another body.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerResponse'
          description: >-
            Internal server error. When `activate` was passed and the draft was
            created, `data` carries it and any validation checks.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayResponse'
          description: >-
            An upstream dependency failed. When `activate` was passed and the
            draft was created, `data` carries it and any validation checks.
        '503':
          description: 'Nemonist: the account service is temporarily unavailable; retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerResponse'
components:
  parameters:
    AppIdentifier:
      name: HTTP-Referer
      in: header
      schema:
        type: string
      description: >
        The app identifier should be your app's URL and is used as the primary
        identifier for rankings.

        This is used to track API usage per application.
    AppDisplayName:
      name: X-OpenRouter-Title
      in: header
      x-speakeasy-name-override: appTitle
      schema:
        type: string
      description: >
        The app display name allows you to customize how your app appears in
        OpenRouter's dashboard.
    AppCategories:
      name: X-OpenRouter-Categories
      in: header
      x-speakeasy-name-override: appCategories
      schema:
        type: string
      description: >
        Comma-separated list of app categories (e.g. "cli-agent,cloud-agent").
        Used for marketplace rankings.
  schemas:
    CreateNemonistEndpointRequest:
      type: object
      description: >-
        A new custom endpoint. model_permaslug, provider_slug, pricing and
        declared_region are refused with 400: a custom endpoint serves its own
        model names and is not billed.
      properties:
        workspace_id:
          type: string
          description: 'The workspace it serves; omitted: the account''s default workspace.'
        slug:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{1,39}$
          description: >-
            Model prefix, 2-40 lower-case letters, digits and dashes; not a
            catalog vendor's name (such as openai).
        name:
          type: string
          maxLength: 100
          description: Display name; empty uses the slug.
        base_url:
          type: string
          description: >-
            Public HTTPS base URL of the OpenAI-compatible server, such as
            https://host/v1. Private and loopback addresses are refused.
        formats:
          type: array
          items:
            type: string
            enum:
              - chat
              - responses
              - messages
          description: >-
            APIs the server speaks: chat (/chat/completions) always, plus
            responses (/responses) and messages (/messages) when listed.
        declared_zdr:
          type:
            - boolean
            - 'null'
          description: >-
            Your word that the server keeps no prompt or completion data; null
            is undeclared.
        upstream_model_id:
          type: string
          maxLength: 200
          description: >-
            The model validation calls, as the server names it; empty uses the
            first model its GET /models lists.
        key:
          type: string
          maxLength: 8000
          description: >-
            The server's API key, sent to it as a bearer token; stored sealed
            and never returned.
        activate:
          description: >-
            true, or {workspace_id}, validates and activates in the same call; a
            failed validation keeps the draft and answers 422.
          anyOf:
            - type: boolean
            - type: object
              description: Activate in this workspace.
              properties:
                workspace_id:
                  type: string
                  description: Same as the top-level workspace_id; the two must agree.
      required:
        - slug
        - base_url
        - key
    NemonistEndpoint:
      type: object
      description: >-
        A custom endpoint: your own OpenAI-compatible server, routed for one
        workspace's keys as <slug>/<model>. The key is write-only and never
        returned.
      properties:
        id:
          type: string
          description: Stable identifier of the endpoint.
        workspace_id:
          type: string
          description: The workspace whose keys route to it.
        slug:
          type: string
          description: >-
            Model prefix: a request for <slug>/<model> goes to this server as
            <model>. Fixed once created.
        name:
          type: string
          maxLength: 100
          description: Display name; empty uses the slug.
        base_url:
          type: string
          description: >-
            Public HTTPS base URL of the OpenAI-compatible server, such as
            https://host/v1. Private and loopback addresses are refused.
        formats:
          type: array
          items:
            type: string
            enum:
              - chat
              - responses
              - messages
          description: >-
            APIs the server speaks: chat (/chat/completions) always, plus
            responses (/responses) and messages (/messages) when listed.
        declared_zdr:
          type:
            - boolean
            - 'null'
          description: >-
            Your word that the server keeps no prompt or completion data; null
            is undeclared.
        upstream_model_id:
          type: string
          maxLength: 200
          description: >-
            The model validation calls, as the server names it; empty uses the
            first model its GET /models lists.
        models:
          type: array
          items:
            type: string
          description: >-
            Model ids the server's GET /models listed at the last validation;
            GET /models shows them as <slug>/<id>.
        status:
          type: string
          enum:
            - draft
            - active
            - disabled
          description: >-
            draft: not routed until validated and activated; active: routed;
            disabled: kept but not routed.
        validation:
          allOf:
            - $ref: '#/components/schemas/NemonistEndpointValidation'
          description: The last validation run; absent before the first.
        created_at:
          type: string
          description: When it was created (RFC 3339).
        updated_at:
          type: string
          description: When it last changed (RFC 3339).
      required:
        - id
        - workspace_id
        - slug
        - name
        - base_url
        - formats
        - models
        - status
        - declared_zdr
        - upstream_model_id
        - created_at
        - updated_at
    BadRequestResponse:
      description: Bad Request - Invalid request parameters or malformed input
      example:
        error:
          code: 400
          message: Invalid request parameters
      properties:
        error:
          $ref: '#/components/schemas/BadRequestResponseErrorData'
        openrouter_metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: OpenRouter's routing detail for the failed request.
        user_id:
          type:
            - string
            - 'null'
          description: Id of the user who made the request.
      required:
        - error
      type: object
    UnauthorizedResponse:
      description: Unauthorized - Authentication required or invalid credentials
      example:
        error:
          code: 401
          message: Missing Authentication header
      properties:
        error:
          $ref: '#/components/schemas/UnauthorizedResponseErrorData'
        openrouter_metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: OpenRouter's routing detail for the failed request.
        user_id:
          type:
            - string
            - 'null'
          description: Id of the user who made the request.
      required:
        - error
      type: object
    ForbiddenResponse:
      description: Forbidden - Authentication successful but insufficient permissions
      example:
        error:
          code: 403
          message: Only management keys can perform this operation
      properties:
        error:
          $ref: '#/components/schemas/ForbiddenResponseErrorData'
        openrouter_metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: OpenRouter's routing detail for the failed request.
        user_id:
          type:
            - string
            - 'null'
          description: Id of the user who made the request.
      required:
        - error
      type: object
    NotFoundResponse:
      description: Not Found - Resource does not exist
      example:
        error:
          code: 404
          message: Resource not found
      properties:
        error:
          $ref: '#/components/schemas/NotFoundResponseErrorData'
        openrouter_metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: OpenRouter's routing detail for the failed request.
        user_id:
          type:
            - string
            - 'null'
          description: Id of the user who made the request.
      required:
        - error
      type: object
    RequestTimeoutResponse:
      description: Request Timeout - Operation exceeded time limit
      example:
        error:
          code: 408
          message: Operation timed out. Please try again later.
      properties:
        error:
          $ref: '#/components/schemas/RequestTimeoutResponseErrorData'
        openrouter_metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: OpenRouter's routing detail for the failed request.
        user_id:
          type:
            - string
            - 'null'
          description: Id of the user who made the request.
      required:
        - error
      type: object
    ConflictResponse:
      description: Conflict - Resource conflict or concurrent modification
      example:
        error:
          code: 409
          message: Resource conflict. Please try again later.
      properties:
        error:
          $ref: '#/components/schemas/ConflictResponseErrorData'
        openrouter_metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: OpenRouter's routing detail for the failed request.
        user_id:
          type:
            - string
            - 'null'
          description: Id of the user who made the request.
      required:
        - error
      type: object
    CreateNemonistEndpointFailedResponse:
      type: object
      description: >-
        activate was passed and validation failed: the draft is kept; fix it,
        then call /validate and /activate.
      properties:
        error:
          type: object
          description: What went wrong.
          properties:
            code:
              type: integer
              description: Always 422.
            message:
              type: string
              description: Human-readable error message.
          required:
            - code
            - message
        data:
          type: object
          description: The kept draft and its failed run.
          properties:
            endpoint:
              $ref: '#/components/schemas/NemonistEndpoint'
            validation:
              $ref: '#/components/schemas/NemonistEndpointValidation'
          required:
            - endpoint
            - validation
      required:
        - error
        - data
    UnprocessableEntityResponse:
      description: Unprocessable Entity - Semantic validation failure
      example:
        error:
          code: 422
          message: Invalid argument
      properties:
        error:
          $ref: '#/components/schemas/UnprocessableEntityResponseErrorData'
        openrouter_metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: OpenRouter's routing detail for the failed request.
        user_id:
          type:
            - string
            - 'null'
          description: Id of the user who made the request.
      required:
        - error
      type: object
    InternalServerResponse:
      description: Internal Server Error - Unexpected server error
      example:
        error:
          code: 500
          message: Internal Server Error
      properties:
        error:
          $ref: '#/components/schemas/InternalServerResponseErrorData'
        openrouter_metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: OpenRouter's routing detail for the failed request.
        user_id:
          type:
            - string
            - 'null'
          description: Id of the user who made the request.
      required:
        - error
      type: object
    BadGatewayResponse:
      description: Bad Gateway - Provider/upstream API failure
      example:
        error:
          code: 502
          message: Provider returned error
      properties:
        error:
          $ref: '#/components/schemas/BadGatewayResponseErrorData'
        openrouter_metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: OpenRouter's routing detail for the failed request.
        user_id:
          type:
            - string
            - 'null'
          description: Id of the user who made the request.
      required:
        - error
      type: object
    NemonistEndpointValidation:
      type: object
      description: 'A validation run: live calls to the server with its key.'
      properties:
        passed:
          type: boolean
          description: >-
            Whether every check passed; activate needs a passing run newer than
            the last change.
        validated_at:
          type: string
          description: When the run finished (RFC 3339).
        checks:
          type: array
          items:
            $ref: '#/components/schemas/NemonistEndpointCheck'
          description: Each check in the order it ran; the first failure ends the run.
      required:
        - passed
        - validated_at
        - checks
    BadRequestResponseErrorData:
      description: Error data for BadRequestResponse
      example:
        code: 400
        message: Invalid request parameters
      properties:
        code:
          type: integer
          description: 'HTTP status of the error, the same as the response''s: 400.'
        message:
          type: string
          description: >-
            What went wrong, in words for a person; do not parse it, branch on
            code instead.
        metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: Extra detail about the error.
      required:
        - code
        - message
      type: object
    UnauthorizedResponseErrorData:
      description: Error data for UnauthorizedResponse
      example:
        code: 401
        message: Missing Authentication header
      properties:
        code:
          type: integer
          description: 'HTTP status of the error, the same as the response''s: 401.'
        message:
          type: string
          description: >-
            What went wrong, in words for a person; do not parse it, branch on
            code instead.
        metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: Extra detail about the error.
      required:
        - code
        - message
      type: object
    ForbiddenResponseErrorData:
      description: Error data for ForbiddenResponse
      example:
        code: 403
        message: Only management keys can perform this operation
      properties:
        code:
          type: integer
          description: 'HTTP status of the error, the same as the response''s: 403.'
        message:
          type: string
          description: >-
            What went wrong, in words for a person; do not parse it, branch on
            code instead.
        metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: Extra detail about the error.
      required:
        - code
        - message
      type: object
    NotFoundResponseErrorData:
      description: Error data for NotFoundResponse
      example:
        code: 404
        message: Resource not found
      properties:
        code:
          type: integer
          description: 'HTTP status of the error, the same as the response''s: 404.'
        message:
          type: string
          description: >-
            What went wrong, in words for a person; do not parse it, branch on
            code instead.
        metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: Extra detail about the error.
      required:
        - code
        - message
      type: object
    RequestTimeoutResponseErrorData:
      description: Error data for RequestTimeoutResponse
      example:
        code: 408
        message: Operation timed out. Please try again later.
      properties:
        code:
          type: integer
          description: 'HTTP status of the error, the same as the response''s: 408.'
        message:
          type: string
          description: >-
            What went wrong, in words for a person; do not parse it, branch on
            code instead.
        metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: Extra detail about the error.
      required:
        - code
        - message
      type: object
    ConflictResponseErrorData:
      description: Error data for ConflictResponse
      example:
        code: 409
        message: Resource conflict. Please try again later.
      properties:
        code:
          type: integer
          description: 'HTTP status of the error, the same as the response''s: 409.'
        message:
          type: string
          description: >-
            What went wrong, in words for a person; do not parse it, branch on
            code instead.
        metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: Extra detail about the error.
      required:
        - code
        - message
      type: object
    UnprocessableEntityResponseErrorData:
      description: Error data for UnprocessableEntityResponse
      example:
        code: 422
        message: Invalid argument
      properties:
        code:
          type: integer
          description: 'HTTP status of the error, the same as the response''s: 422.'
        message:
          type: string
          description: >-
            What went wrong, in words for a person; do not parse it, branch on
            code instead.
        metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: Extra detail about the error.
      required:
        - code
        - message
      type: object
    InternalServerResponseErrorData:
      description: Error data for InternalServerResponse
      example:
        code: 500
        message: Internal Server Error
      properties:
        code:
          type: integer
          description: 'HTTP status of the error, the same as the response''s: 500.'
        message:
          type: string
          description: >-
            What went wrong, in words for a person; do not parse it, branch on
            code instead.
        metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: Extra detail about the error.
      required:
        - code
        - message
      type: object
    BadGatewayResponseErrorData:
      description: Error data for BadGatewayResponse
      example:
        code: 502
        message: Provider returned error
      properties:
        code:
          type: integer
          description: 'HTTP status of the error, the same as the response''s: 502.'
        message:
          type: string
          description: >-
            What went wrong, in words for a person; do not parse it, branch on
            code instead.
        metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: Extra detail about the error.
      required:
        - code
        - message
      type: object
    NemonistEndpointCheck:
      type: object
      description: One validation check.
      properties:
        name:
          type: string
          enum:
            - base_url
            - auth_ok
            - models
            - chat
            - usage
            - stream
            - responses
            - messages
          description: >-
            The check: base_url reachable, auth_ok the key accepted, models GET
            /models lists upstream_model_id, chat/usage/stream a real call,
            responses/messages each declared format.
        passed:
          type: boolean
          description: Whether the check passed.
        reason:
          type: string
          enum:
            - invalid_base_url
            - upstream_error
            - invalid_response
            - invalid_stream
            - missing_usage
            - model_mismatch
          description: Why the check failed; absent when it passed.
        upstream_status:
          type: integer
          description: HTTP status the server answered, when the call failed.
        upstream_message:
          type: string
          description: >-
            The server's error message (at most 300 characters), when the call
            failed.
        actual_model:
          type: string
          description: The model the check called or the server reported serving.
      required:
        - name
        - passed
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        A Nemonist key (sk-nm-...) as a bearer token in the Authorization
        header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.