Paper Instruments API

openapi: 3.1.0
info:
  title: Paper Instruments API
  version: '2026-10-29'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-29: 8 operation(s) read from 7 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Paper Instruments has published no machine-readable contract
    that the pipeline could find. Engine: anthropic.'
  x-evidence-tiers:
    code-example: 1
    documentation: 7
    pages-with-code: 2
    pages-read: 7
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-29'
  x-generator: generate-contract-from-docs.py
  x-engine: anthropic
  x-sources:
  - https://docs.paperinstruments.com/docs/ultramarine
  - https://docs.paperinstruments.com/docs/ultramarine/messages
  - https://docs.paperinstruments.com/docs/ultramarine/responses
  - https://docs.paperinstruments.com/docs/ultramarine/chat-completions
  - https://docs.paperinstruments.com/docs/ultramarine/billing
  - https://docs.paperinstruments.com/docs/ultramarine/sticky-sessions
  - https://docs.paperinstruments.com/docs/ultramarine/rate-limits
servers:
- url: https://api.paperinstruments.com
paths:
  /v1:
    get:
      operationId: get_v1
      tags:
      - Api
      summary: GET /v1
      x-source: https://docs.paperinstruments.com/docs/ultramarine
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl pip install -U openai example.py import os \n from openai import OpenAI \n client = OpenAI( \n base_url = \"https://api.paperinstruments.com/v1\"\
          \ , \n api_key = os.environ[ \"PAPERINSTRUMENTS_API_KEY\" ], \n ) \n stream = client.chat.completions.create( \n model = \"ultramarine-1-flash\"\
          \ , \n messages = [{ \"role\" : \"user\" , \"content\" : \"Explain EBITDA in two sentences.\" }], \n reasoning_effort = \"max\" , \n\
          \ m"
  /v1/chat/completions:
    post:
      operationId: post_v1_chat_completions
      tags:
      - Chat
      summary: Create a chat completion.
      x-source: https://docs.paperinstruments.com/docs/ultramarine/chat-completions
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer $PAPERINSTRUMENTS_API_KEY
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ChatCompletionsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ChatCompletionsResponse'
      x-evidence:
        kind: documentation
  /v1/messages:
    post:
      operationId: post_v1_messages
      tags:
      - Messages
      summary: Send a message to the Ultramarine API using the Anthropic Messages format.
      x-source: https://docs.paperinstruments.com/docs/ultramarine/messages
      parameters:
      - name: model
        in: query
        required: true
        schema:
          type: string
        description: Required. ultramarine-1-flash
      - name: max_tokens
        in: query
        required: true
        schema:
          type: integer
        description: Required. Positive integer, including reasoning. The default output limit is 65,536 tokens.
      - name: messages
        in: query
        required: true
        schema:
          type: array
        description: Required. user and assistant turns, ending with a user turn
      - name: system
        in: query
        required: false
        schema:
          type: string
        description: String or text blocks
      - name: output_config.effort
        in: query
        required: false
        schema:
          type: string
        description: 'low, high, or max. Default: max'
      - name: output_config.format
        in: query
        required: false
        schema:
          type: object
        description: '{"type": "json_schema", "schema": {...}}'
      - name: thinking
        in: query
        required: false
        schema:
          type: object
        description: '{"type": "adaptive"}, optionally with "display": "omitted"'
      - name: stream
        in: query
        required: false
        schema:
          type: boolean
        description: true or false
      - name: tools
        in: query
        required: false
        schema:
          type: array
        description: Custom tools with name, description, input_schema, and optional strict
      - name: tool_choice
        in: query
        required: false
        schema:
          type: string
        description: 'auto, any, none, or {"type": "tool", "name": "..."}, with optional disable_parallel_tool_use'
      - name: temperature
        in: query
        required: false
        schema:
          type: number
        description: 'Number, 0–1. Default and recommended: 1'
      - name: top_p
        in: query
        required: false
        schema:
          type: number
        description: 'Number, 0–1. Default and recommended: 0.95'
      - name: top_k
        in: query
        required: false
        schema:
          type: integer
        description: 'Integer, -1 or greater. Default and recommended: -1 (disabled)'
      - name: metadata.user_id
        in: query
        required: false
        schema:
          type: string
        description: String, up to 512 characters
      - name: cache_control
        in: query
        required: false
        schema:
          type: object
        description: '{"type": "ephemeral"}'
      - name: context_management
        in: query
        required: false
        schema:
          type: object
        description: '{"edits": [{"type": "clear_thinking_20251015", "keep": "all"}]}'
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
        description: '2023-06-01'
      - name: x-session-id
        in: header
        required: false
        schema:
          type: string
        description: Optional. A stable conversation ID for sticky routing
      - name: anthropic-beta
        in: header
        required: false
        schema:
          type: string
        description: claude-code-20250219, mid-conversation-system-2026-04-07, effort-2025-11-24, interleaved-thinking-2025-05-14, context-management-2025-06-27
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1MessagesRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1MessagesResponse'
      x-evidence:
        kind: documentation
  /v1/models:
    get:
      operationId: get_v1_models
      tags:
      - Models
      summary: Lists available models.
      x-source: https://docs.paperinstruments.com/docs/ultramarine/chat-completions
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/models/{id}:
    get:
      operationId: get_v1_models_id
      tags:
      - Models
      summary: Retrieves one model.
      x-source: https://docs.paperinstruments.com/docs/ultramarine/chat-completions
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/pricing:
    get:
      operationId: get_v1_pricing
      tags:
      - Pricing
      summary: Returns the current rates without authentication.
      x-source: https://docs.paperinstruments.com/docs/ultramarine/billing
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1PricingResponse'
      x-evidence:
        kind: documentation
  /v1/responses:
    post:
      operationId: post_v1_responses
      tags:
      - Responses
      summary: POST /v1/responses
      x-source: https://docs.paperinstruments.com/docs/ultramarine/responses
      parameters:
      - name: model
        in: query
        required: true
        schema:
          type: string
        description: ultramarine-1-flash
      - name: input
        in: query
        required: false
        schema:
          type: string
        description: 'A string or an array of Responses input items. Default: []'
      - name: instructions
        in: query
        required: false
        schema:
          type: string
        description: Optional string. Send instructions again on subsequent requests.
      - name: reasoning.effort
        in: query
        required: false
        schema:
          type: string
        description: 'low, high, or max. Default: max'
      - name: max_output_tokens
        in: query
        required: false
        schema:
          type: integer
        description: Positive integer, including reasoning. Omit to use the default output limit of 65,536 tokens.
      - name: store
        in: query
        required: false
        schema:
          type: boolean
        description: Only false is supported, which is the default.
      - name: stream
        in: query
        required: false
        schema:
          type: boolean
        description: 'Boolean. Default: false. Use true for typed server-sent events.'
      - name: tools
        in: query
        required: false
        schema:
          type: array
        description: Array of function, mcp, or web_search definitions.
      - name: tool_choice
        in: query
        required: false
        schema:
          type: string
        description: auto, none, required, or object with type and name/web_search
      - name: parallel_tool_calls
        in: query
        required: false
        schema:
          type: boolean
        description: Boolean
      - name: max_tool_calls
        in: query
        required: false
        schema:
          type: integer
        description: 'Integer, 1–15; default: 4'
      - name: text.format
        in: query
        required: false
        schema:
          type: string
        description: '{"type":"text"}, {"type":"json_object"}, or json_schema'
      - name: temperature
        in: query
        required: false
        schema:
          type: number
        description: 'Number, 0–2. Default and recommended: 1'
      - name: top_p
        in: query
        required: false
        schema:
          type: number
        description: 'Number, 0–1. Default and recommended: 0.95'
      - name: metadata
        in: query
        required: false
        schema:
          type: string
        description: 'Up to 16 string pairs. Keys: at most 64 characters; values: at most 512.'
      - name: prompt_cache_key
        in: query
        required: false
        schema:
          type: string
        description: Optional string cache hint. Cache hits are not guaranteed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ResponsesRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ResponsesResponse'
      x-evidence:
        kind: documentation
  /v1/usage:
    get:
      operationId: get_v1_usage
      tags:
      - Usage
      summary: Call GET /v1/usage with an API key for organization usage in the current UTC calendar month.
      x-source: https://docs.paperinstruments.com/docs/ultramarine/billing
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1UsageResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    PostV1ChatCompletionsRequest:
      type: object
      properties:
        model:
          type: string
          description: ultramarine-1-flash
        messages:
          type: string
          description: 'Required, non-empty array. Roles: system, user, assistant, tool'
        reasoning_effort:
          type: string
          description: 'low, high, or max. Default: max'
        max_completion_tokens:
          type: string
          description: Positive integer, including reasoning
        stream:
          type: string
          description: 'Boolean. Default: false'
        stream_options:
          type: string
          description: 'Set {"include_usage": true} to receive stream usage'
        tools:
          type: string
          description: Function tools and tool selection
        tool_choice:
          type: string
          description: Tool selection
        parallel_tool_calls:
          type: string
          description: Parallel tool calls
        response_format:
          type: string
          description: 'Structured output: json_object or json_schema, or plain text'
        temperature:
          type: string
          description: 'Number, 0–2. Default and recommended: 1'
        top_p:
          type: string
          description: 'Number, 0–1. Default and recommended: 0.95'
        top_k:
          type: string
          description: 'Integer, -1 or greater. Default and recommended: -1'
        min_p:
          type: string
          description: Minimum-probability sampling control
        presence_penalty:
          type: string
          description: Token selection control
        frequency_penalty:
          type: string
          description: Token selection control
        repetition_penalty:
          type: string
          description: Token selection control
        logit_bias:
          type: string
          description: Token selection control
        logprobs:
          type: string
          description: Token probabilities
        top_logprobs:
          type: string
          description: Token probabilities. Must be an integer, 0–20
        n:
          type: string
          description: 'Integer, 1–16. Default: 1'
        stop:
          type: string
          description: A string or up to 16 non-empty strings, each at most 1,024 characters
        seed:
          type: string
          description: Sampling seed
        prompt_cache_key:
          type: string
          description: Optional cache hint
        user:
          type: string
          description: User identifier
      required:
      - model
      - messages
    PostV1ChatCompletionsResponse:
      type: object
      properties:
        choices:
          type: string
        usage:
          type: string
    PostV1MessagesRequest:
      type: object
      properties:
        model:
          type: string
          description: Required. ultramarine-1-flash
        max_tokens:
          type: integer
          description: Required. Positive integer, including reasoning
        messages:
          type: array
          description: Required. user and assistant turns, ending with a user turn
        system:
          type: string
          description: String or text blocks
        output_config:
          type: object
          description: Object with effort and format fields
        thinking:
          type: object
          description: '{"type": "adaptive"}, optionally with "display": "omitted"'
        stream:
          type: boolean
          description: true or false
        tools:
          type: array
          description: Custom tools with name, description, input_schema, and optional strict
        tool_choice:
          type: string
          description: auto, any, none, or tool object
        temperature:
          type: number
          description: Number, 0–1
        top_p:
          type: number
          description: Number, 0–1
        top_k:
          type: integer
          description: Integer, -1 or greater
        metadata:
          type: object
          description: Object with user_id field
        cache_control:
          type: object
          description: '{"type": "ephemeral"}'
        context_management:
          type: object
          description: Object with edits array
      required:
      - model
      - max_tokens
      - messages
    PostV1MessagesResponse:
      type: object
      properties:
        type:
          type: string
          description: Response type
        error:
          type: object
          description: Error object containing type and message
        request_id:
          type: string
          description: Request ID prefixed with req_
    GetV1PricingResponse:
      type: object
      properties:
        web_search_per_1k_usd:
          type: number
    PostV1ResponsesRequest:
      type: object
      properties:
        model:
          type: string
          description: Required. ultramarine-1-flash
        input:
          type: string
          description: 'A string or an array of Responses input items. Default: []'
        instructions:
          type: string
          description: Optional string. Send instructions again on subsequent requests.
        reasoning:
          type: object
          description: 'reasoning.effort: low, high, or max. Default: max'
        max_output_tokens:
          type: integer
          description: Positive integer, including reasoning.
        store:
          type: boolean
          description: Only false is supported, which is the default.
        previous_response_id:
          type: string
          description: Unsupported.
        stream:
          type: boolean
          description: 'Boolean. Default: false.'
        tools:
          type: array
          description: Array of function, mcp, or web_search definitions.
        tool_choice:
          type: string
          description: auto, none, required, or object
        parallel_tool_calls:
          type: boolean
          description: Boolean.
        max_tool_calls:
          type: integer
          description: 'Integer, 1–15; default: 4'
        text:
          type: object
          description: text.format field
        temperature:
          type: number
          description: 'Number, 0–2. Default and recommended: 1'
        top_p:
          type: number
          description: 'Number, 0–1. Default and recommended: 0.95'
        metadata:
          type: object
          description: Up to 16 string pairs.
        prompt_cache_key:
          type: string
          description: Optional string cache hint.
      required:
      - model
    PostV1ResponsesResponse:
      type: object
      properties:
        status:
          type: string
          description: Response status
        output_text:
          type: string
          description: The text output of the response
        output:
          type: array
          description: Each step's reasoning and messages, plus tool calls
        usage:
          type: object
          description: Token usage including input_tokens, output_tokens, total_tokens
        id:
          type: string
          description: Response ID
    GetV1UsageResponse:
      type: object
      properties:
        available_nanodollars:
          type: number
        reserved_nanodollars:
          type: number
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
security:
- apiKey: []
tags:
- name: Api
- name: Chat
- name: Messages
- name: Models
- name: Pricing
- name: Responses
- name: Usage