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

# Post v1systemone



## OpenAPI

````yaml /api-reference/openapi.json post /v1/systemone
openapi: 3.1.0
info:
  title: NEAR AI Cloud API
  description: >-
    NEAR AI Cloud API for private AI model inference and organization
    administration.
  contact:
    name: NEAR AI Team
    email: support@near.ai
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://cloud-api.near.ai
    description: NEAR AI Cloud
security:
  - session_token: []
  - api_key: []
tags:
  - name: Chat
    description: Chat completion endpoints for AI model inference
  - name: Images
    description: Image generation endpoints
  - name: Decisions
    description: Typed decisions through the System One protocol
  - name: Audio
    description: Audio transcription endpoints
  - name: Rerank
    description: Document reranking endpoints
  - name: Score
    description: Text similarity scoring endpoints
  - name: Privacy
    description: Privacy classification (PII span detection) endpoints
  - name: Models
    description: Public model catalog and information
  - name: Conversations
    description: >-
      Temporary authenticated, workspace-scoped migration access for export and
      account deletion. Only `POST /v1/conversations/batch`, `GET
      /v1/conversations/{conversation_id}`, `GET
      /v1/conversations/{conversation_id}/items`, and `DELETE
      /v1/conversations/{conversation_id}` are available. Conversation creation
      and every other mutation return `410 Gone`; this surface will be removed
      after data migration. Migration responses use `Cache-Control: no-store`.
  - name: Files
    description: >-
      Temporary authenticated, workspace-scoped migration access for export and
      account deletion. Only `GET /v1/files`, `GET /v1/files/{file_id}`, `GET
      /v1/files/{file_id}/content`, and `DELETE /v1/files/{file_id}` are
      available. Upload and every other mutation return `410 Gone`; this surface
      will be removed after data migration. Migration responses use
      `Cache-Control: no-store`.
  - name: Responses
    description: >-
      Stateless response inference. Both paths normalize omitted or null `store`
      to `false` and reject `store: true`. Raw request/response content,
      response items, and history are not persisted. Clients must include any
      prior context in each request. Canonical `openai/` models use one upstream
      native Responses request after alias resolution. Other models use the
      typed adapter, with bounded request-scoped inference rounds when hosted
      search is requested.


      Both paths accept client-managed `function` and `custom` tools, including
      tools grouped in a `namespace`, and leading developer `additional_tools`
      declarations. Cloud returns calls without executing them; clients replay
      each `function_call` or `custom_tool_call` with its matching output and
      caller-managed history. Preserve `call_id`, names, namespaces, raw
      arguments or custom input, and provider metadata such as
      `thought_signature`. The typed replay path accepts assistant `output_text`
      parts and plaintext `reasoning` items, using reasoning content or its
      summary as prior assistant context. Encrypted-only reasoning requires a
      native Responses backend. The typed adapter supports text custom tools and
      the Codex `exec` Lark source grammar; other grammars require a native
      backend.


      Each generated item has its own `output_index`. Tool calls finish with
      `response.output_item.done`; a successful model turn ends with
      `response.completed`, including when tools await client execution.
      Reasoning uses `response.reasoning_text.delta`; failures expose
      `response.error` in `response.failed` and preserve partial usage.


      The typed adapter executes `web_search` and `web_context_search` using a
      bounded request-scoped loop, emits search lifecycle events and URL
      citations, and accumulates usage across inference rounds without storing
      history. Optional `web_search.count` (0–20) overrides model-selected
      counts; 0 skips the search provider. If a model emits client tool calls
      and searches in the same round, client calls are returned without
      executing that round's searches. On the typed path, completed search
      output markers may accompany replayed assistant text, but raw search
      results are not restored across requests. Native Responses also accepts
      top-level `web_search`, executed by the upstream provider without a Cloud
      search loop. Complete native `web_search_call` replay items, search
      configuration, and `include` are forwarded unchanged; provider-returned
      search citations and sources retain their native shape. `file_search`,
      `code_interpreter`, `computer`, and remote `mcp` are unsupported.
      Image-generation/editing models are rejected on both paths. The separate
      `POST /mcp` endpoint exposes its `web_search` tool independently of
      Responses; use `/v1/images/*` for image generation/editing. Existing
      completed-response gateway attestation is preserved best-effort: when the
      signature write succeeds, `GET /v1/signature/resp_*` retrieves signatures
      over SHA-256 request/response digests, never raw content. Interrupted
      streams create no `resp_*` attestation record or legacy disconnect
      fallback. Responses rejects conversation linkage, response history, and
      file input; the separate Conversation and File endpoints are not part of
      Responses inference.
  - name: Organizations
    description: Organization management
  - name: Organization Members
    description: Organization member and invitation management
  - name: Workspaces
    description: Workspace and API key management
  - name: Users
    description: User profile and token management
  - name: Invitations
    description: Token-based invitation handling
  - name: Usage
    description: Usage tracking and billing information
  - name: Reporting
    description: Read-only customer usage reporting
  - name: Billing
    description: Billing costs endpoint (HuggingFace integration)
  - name: Staking Farm
    description: House of Stake farm credit configuration and synchronization
  - name: Health
    description: Health check endpoints
  - name: Attestation
    description: Attestation and verification endpoints
  - name: Gateway
    description: Model gateway integration endpoints
  - name: Admin
    description: Administrative endpoints (admin access required)
  - name: Services
    description: Public platform services (e.g. web_search pricing)
paths:
  /v1/systemone:
    post:
      tags:
        - Decisions
      operationId: systemone
      parameters:
        - name: x-model-pub-key
          in: header
          description: >-
            Signing public key from the model attestation, used for plaintext
            routing
          required: false
          schema:
            type:
              - string
              - 'null'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SystemOneRequest'
        required: true
      responses:
        '200':
          description: >-
            Typed decisions. X-Generation-Id identifies the receipt at
            /v1/signature/{id}; Inference-Id identifies billing usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemOneResponse'
        '400':
          description: Invalid request or model modality
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '421':
          description: Selected model signing key is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate or concurrency limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Invalid provider response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - api_key: []
components:
  schemas:
    SystemOneRequest:
      type: object
      required:
        - model
        - state
        - questions
      properties:
        assets:
          type:
            - object
            - 'null'
          additionalProperties:
            $ref: '#/components/schemas/SystemOneImageAsset'
          propertyNames:
            type: string
        model:
          type: string
        questions:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SystemOneQuestion'
          propertyNames:
            type: string
        state:
          $ref: '#/components/schemas/SystemOneContent'
      additionalProperties: false
    SystemOneResponse:
      type: object
      required:
        - model
        - answers
        - usage
      properties:
        answers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SystemOneAnswer'
          propertyNames:
            type: string
        id:
          type:
            - string
            - 'null'
          description: >-
            Optional upstream ID. Required by our self-hosted TEE signing
            contract.

            TypeSafe's hosted API omits it; the gateway exposes X-Generation-Id
            instead.
        model:
          type: string
        usage:
          $ref: '#/components/schemas/SystemOneUsage'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
    SystemOneImageAsset:
      type: object
      description: >-
        JSON image data keyed by reference; reference resolution belongs to the
        provider.
      required:
        - format
        - data_base64
      properties:
        data_base64:
          type: string
        format:
          $ref: '#/components/schemas/SystemOneImageFormat'
        type:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/SystemOneImageAssetType'
      additionalProperties: false
    SystemOneQuestion:
      oneOf:
        - type: object
          required:
            - instructions
            - type
          properties:
            criteria:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/SystemOneNoulCriteria'
            instructions:
              $ref: '#/components/schemas/SystemOneContent'
            type:
              type: string
              enum:
                - noul
        - type: object
          required:
            - instructions
            - criteria
            - type
          properties:
            criteria:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/SystemOneChoiceCriterion'
              propertyNames:
                type: string
            instructions:
              $ref: '#/components/schemas/SystemOneContent'
            type:
              type: string
              enum:
                - choice
        - type: object
          required:
            - instructions
            - criteria
            - type
          properties:
            criteria:
              type: array
              items:
                $ref: '#/components/schemas/SystemOneContent'
            instructions:
              $ref: '#/components/schemas/SystemOneContent'
            type:
              type: string
              enum:
                - score
        - type: object
          required:
            - instructions
            - type
          properties:
            instructions:
              $ref: '#/components/schemas/SystemOneContent'
            type:
              type: string
              enum:
                - box
    SystemOneContent:
      oneOf:
        - type: string
        - type: object
          additionalProperties: {}
          propertyNames:
            type: string
        - type: array
          items: {}
      description: Text or structured context accepted by the System One protocol.
    SystemOneAnswer:
      oneOf:
        - type: object
          required:
            - noul
            - type
          properties:
            noul:
              type: number
              format: double
            type:
              type: string
              enum:
                - noul
        - type: object
          required:
            - choice
            - confidence
            - probabilities
            - type
          properties:
            choice:
              type: string
            confidence:
              type: number
              format: double
            probabilities:
              type: object
              additionalProperties:
                type: number
                format: double
              propertyNames:
                type: string
            type:
              type: string
              enum:
                - choice
        - type: object
          required:
            - score
            - confidence
            - probabilities
            - legend
            - type
          properties:
            confidence:
              type: number
              format: double
            legend:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/SystemOneContent'
              propertyNames:
                type: string
            probabilities:
              type: object
              additionalProperties:
                type: number
                format: double
              propertyNames:
                type: string
            score:
              type: number
              format: double
            type:
              type: string
              enum:
                - score
        - type: object
          required:
            - box
            - type
          properties:
            box:
              $ref: '#/components/schemas/SystemOneBoxCoordinates'
            confidence:
              type:
                - number
                - 'null'
              format: double
            type:
              type: string
              enum:
                - box
    SystemOneUsage:
      type: object
      required:
        - input_tokens
        - output_tokens
      properties:
        input_tokens:
          type: integer
          format: int32
        output_tokens:
          type: integer
          format: int32
    ErrorDetail:
      type: object
      required:
        - message
        - type
      properties:
        code:
          type:
            - string
            - 'null'
        message:
          type: string
        param:
          type:
            - string
            - 'null'
        type:
          type: string
    SystemOneImageFormat:
      type: string
      enum:
        - png
        - jpg
        - jpeg
    SystemOneImageAssetType:
      type: string
      enum:
        - image
    SystemOneNoulCriteria:
      type: object
      properties:
        'false':
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/SystemOneContent'
        'true':
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/SystemOneContent'
      additionalProperties: false
    SystemOneChoiceCriterion:
      oneOf:
        - type: 'null'
        - $ref: '#/components/schemas/SystemOneContent'
          description: >-
            A choice may be identified solely by its name, with a null
            description.
    SystemOneBoxCoordinates:
      type: object
      required:
        - top
        - bottom
        - left
        - right
      properties:
        bottom:
          type: number
          format: double
        left:
          type: number
          format: double
        right:
          type: number
          format: double
        top:
          type: number
          format: double
  securitySchemes:
    session_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT access token for user authentication (Authorization: Bearer
        <jwt_token>). Create via POST /users/me/access_tokens.
    api_key:
      type: http
      scheme: bearer
      bearerFormat: api_key
      description: 'API key for programmatic access (Authorization: Bearer sk-<api_key>)'

````

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