openapi: 3.1.0
info:
  title: Restack Agents API
  description: The Restack API provides REST endpoints for scheduling, triggering, and managing AI agents and workflows. Restack automatically generates REST API endpoints for each agent and workflow registered in the platform, allowing programmatic invocation from any client application. Authentication is supported via Bearer tokens for secure access control.
  version: 1.0.0
  contact:
    name: Restack
    url: https://www.restack.io/
  license:
    name: Proprietary
    url: https://www.restack.io/terms
servers:
- url: http://localhost:6233
  description: Restack Local Server
- url: https://api.restack.io
  description: Restack Cloud API
security:
- bearerAuth: []
tags:
- name: Agents
paths:
  /api/agents/{agentName}:
    post:
      operationId: scheduleAgent
      summary: Schedule Agent
      description: Schedule an AI agent by name. The agent will be executed asynchronously and the request will return immediately with a run ID that can be used to track the execution. Inputs and outputs must have types defined.
      tags:
      - Agents
      parameters:
      - name: agentName
        in: path
        required: true
        description: The name of the agent to schedule.
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRunRequest'
      responses:
        '200':
          description: Agent scheduled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
        '404':
          description: Agent not found
        '500':
          description: Internal server error
  /api/agents/{agentName}/{runId}:
    get:
      operationId: getAgentRun
      summary: Get Agent Run
      description: Retrieve the status and result of a specific agent run by run ID.
      tags:
      - Agents
      parameters:
      - name: agentName
        in: path
        required: true
        schema:
          type: string
      - name: runId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Agent run details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunStatus'
        '404':
          description: Agent run not found
components:
  schemas:
    AgentRunResponse:
      type: object
      properties:
        runId:
          type: string
          description: Unique identifier for the agent run.
        status:
          type: string
          enum:
          - queued
          - running
          - completed
          - failed
    AgentRunRequest:
      type: object
      properties:
        input:
          type: object
          description: Input parameters for the agent. Must match the agent's defined input schema.
          additionalProperties: true
    AgentRunStatus:
      type: object
      properties:
        runId:
          type: string
        agentName:
          type: string
        status:
          type: string
          enum:
          - queued
          - running
          - completed
          - failed
        output:
          type: object
          additionalProperties: true
        error:
          type: string
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token for API authentication. Set via RESTACK_API_BEARER_TOKEN environment variable.