openapi: 3.1.0
info:
  title: Anduril Lattice REST Entities Tasks API
  version: v1
  description: 'REST/JSON surface of the Anduril Lattice SDK. Lattice exposes a common operating-picture data fabric for defense partners. The API is organized around three resource families: Entities (anything of operational significance: assets, tracks, geos, sensors), Tasks (sequential commands issued to connected agents with lifecycle and acknowledgements), and Objects (distributed binary payloads such as imagery and telemetry, up to 1 GiB). Authentication uses OAuth 2.0 client credentials to mint short-lived bearer tokens, or direct partner-issued bearer tokens. Production environments are partner-gated and subject to U.S. export controls (ITAR/EAR). Endpoints were reconstructed from the public Lattice SDK reference; gRPC/Protobuf transports are also available but are not described here.'
  contact:
    name: Anduril Developer Portal
    url: https://developer.anduril.com/
servers:
- url: https://api.{environment}.anduril.com
  description: Partner-specific Lattice environment
  variables:
    environment:
      default: developer
      description: Lattice environment subdomain provisioned for the partner
security:
- bearerAuth: []
- oauth2ClientCredentials: []
tags:
- name: Tasks
  description: Create, update, query, cancel, and stream tasks; agent-side listen/stream endpoints.
paths:
  /tasks:
    post:
      tags:
      - Tasks
      summary: Create a task
      description: Create a new task with an auto-generated or specified ID; initializes with STATUS_CREATED.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '200':
          description: Task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
  /tasks/{task_id}:
    get:
      tags:
      - Tasks
      summary: Get a task by ID
      parameters:
      - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: Task details including status, specification, and relations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
  /tasks/{task_id}/status:
    patch:
      tags:
      - Tasks
      summary: Update task status
      description: Update task status as it progresses; increments status_version for optimistic consistency.
      parameters:
      - $ref: '#/components/parameters/TaskId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                status_version:
                  type: integer
      responses:
        '200':
          description: Status updated
  /tasks/{task_id}:cancel:
    post:
      tags:
      - Tasks
      summary: Cancel a task
      description: Immediate cancellation if the task has not been sent to an agent; otherwise routes to the agent for decision.
      parameters:
      - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: Cancellation accepted
  /tasks:query:
    post:
      tags:
      - Tasks
      summary: Query tasks
      description: Search tasks by parent ID, status, time range, assignee, and type. Paginated.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                parent_task_id:
                  type: string
                statuses:
                  type: array
                  items:
                    type: string
                assignee:
                  type: string
                task_type:
                  type: string
                start_time:
                  type: string
                  format: date-time
                end_time:
                  type: string
                  format: date-time
                page_size:
                  type: integer
                page_token:
                  type: string
      responses:
        '200':
          description: Page of tasks
          content:
            application/json:
              schema:
                type: object
                properties:
                  tasks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
                  next_page_token:
                    type: string
  /tasks:stream:
    get:
      tags:
      - Tasks
      summary: Stream tasks (SSE)
      description: SSE stream delivering existing non-terminal tasks and real-time updates with heartbeats.
      responses:
        '200':
          description: SSE stream of task updates
          content:
            text/event-stream:
              schema:
                type: string
  /tasks:listenAsAgent:
    post:
      tags:
      - Tasks
      summary: Long-poll as an agent
      description: Long-poll connection for agents to receive ExecuteRequest, CancelRequest, and CompleteRequest messages.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                agent_id:
                  type: string
                session_token:
                  type: string
      responses:
        '200':
          description: Agent task requests
  /tasks:streamAsAgent:
    get:
      tags:
      - Tasks
      summary: Stream as an agent (SSE)
      description: SSE stream for agents to receive task requests (Execute, Cancel, Complete) with heartbeats.
      responses:
        '200':
          description: SSE stream of agent task requests
          content:
            text/event-stream:
              schema:
                type: string
  /tasks/{task_id}/manualControlFrames:stream:
    get:
      tags:
      - Tasks
      summary: Stream manual control frames (SSE)
      description: SSE stream delivering manual control frames to the executing agent; terminates at task completion.
      parameters:
      - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: SSE stream of manual control frames
          content:
            text/event-stream:
              schema:
                type: string
components:
  parameters:
    TaskId:
      name: task_id
      in: path
      required: true
      description: Unique identifier of the task.
      schema:
        type: string
  schemas:
    Task:
      type: object
      description: A sequential command issued to a Lattice-connected agent.
      properties:
        task_id:
          type: string
        display_name:
          type: string
        description:
          type: string
        specification:
          type: object
        status:
          type: object
          properties:
            status:
              type: string
              enum:
              - STATUS_CREATED
              - STATUS_SENT
              - STATUS_ACKED
              - STATUS_EXECUTING
              - STATUS_DONE_OK
              - STATUS_DONE_NOT_OK
              - STATUS_CANCELED
            status_version:
              type: integer
        relations:
          type: object
        assignee:
          type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token issued via /oauth/token or partner-issued bearer.
    oauth2ClientCredentials:
      type: oauth2
      description: OAuth 2.0 client credentials flow for service-to-service access.
      flows:
        clientCredentials:
          tokenUrl: https://api.developer.anduril.com/oauth/token
          scopes: {}