openapi: 3.1.0
info:
  title: Nomic Atlas API
  version: "1.0"
  description: |
    REST API for the Nomic Platform (Atlas), covering text embedding generation,
    file upload, document parsing, and asynchronous task status. Documented from
    the public Nomic developer docs at https://docs.nomic.ai.
  contact:
    name: Nomic AI
    url: https://docs.nomic.ai
servers:
  - url: https://api-atlas.nomic.ai
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/embedding/text:
    post:
      operationId: embedText
      summary: Generate text embeddings
      description: Generate embeddings for one or more text inputs using a Nomic embedding model.
      tags: [Embeddings]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [texts]
              properties:
                model:
                  type: string
                  description: Embedding model to use.
                  example: nomic-embed-text-v1.5
                texts:
                  type: array
                  description: Texts to embed.
                  items:
                    type: string
                task_type:
                  type: string
                  description: Intended usage for the embedding.
                  enum: [search_document, search_query, classification, clustering]
                  default: search_document
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  embeddings:
                    type: array
                    items:
                      type: array
                      items: { type: number, format: float }
                  model:
                    type: string
                  usage:
                    type: object
                    additionalProperties: true
        "422":
          $ref: "#/components/responses/ValidationError"
  /v1/upload:
    post:
      operationId: createUploadUrls
      summary: Get presigned URLs to upload files
      description: Get URLs to upload files for use in other tasks (parsing, extraction, etc.).
      tags: [Files]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                files:
                  type: array
                  items:
                    type: object
                    properties:
                      filename: { type: string }
                      content_type: { type: string }
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  uploads:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
  /v1/parse:
    post:
      operationId: parseFile
      summary: Parse a file into structured information
      description: Parse a PDF file with configurable chunking strategies and optional embedding generation. Returns a task id for asynchronous polling.
      tags: [Files]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                file_id:
                  type: string
                  description: Identifier of the previously uploaded file.
                chunking_strategy:
                  type: string
                generate_embeddings:
                  type: boolean
      responses:
        "201":
          description: Parsing task created
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id: { type: string }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
  /v1/task/{task_id}:
    get:
      operationId: getTaskStatus
      summary: Get the status of a task
      description: Retrieve the status of an asynchronous task (parsing, extraction).
      tags: [Tasks]
      parameters:
        - in: path
          name: task_id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Task status
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id: { type: string }
                  status: { type: string }
                  result:
                    type: object
                    additionalProperties: true
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        API key passed as a Bearer token in the Authorization header:
        `Authorization: Bearer NOMIC_API_KEY`.
  responses:
    Forbidden:
      description: The user is not authorized to perform this action.
      content:
        application/json:
          schema:
            type: object
            properties:
              detail: { type: string }
    ValidationError:
      description: Validation Error
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: array
                items:
                  type: object
                  additionalProperties: true
tags:
  - name: Embeddings
  - name: Files
  - name: Tasks