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

# Run Agent

> Execute an agent with provided inputs and return results immediately.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url "https://api.roe-ai.com/v1/agents/run/YOUR_AGENT_ID/" \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "inputs": {
        "key": "value"
      }
    }'
  ```
</RequestExample>


## OpenAPI

````yaml POST /v1/agents/run/{agent_id}/
openapi: 3.1.0
info:
  title: Roe API
  version: 1.0.0
  description: Complete API documentation for Roe platform
servers:
  - url: https://api.roe-ai.com
    description: Production API
security: []
paths:
  /v1/agents/run/{agent_id}/:
    post:
      tags:
        - v1
      summary: Run agent synchronously
      description: Execute an agent with provided inputs and return results immediately.
      operationId: agents_run_2
      parameters:
        - in: path
          name: agent_id
          schema:
            type: string
            format: uuid
          required: true
        - name: organization_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: >-
            Organization ID. This is required for access control. It can be
            provided via query or request body depending on the endpoint.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentExecutionRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentDatum'
          description: Agent job result
        '400':
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      type: string
                    description: >-
                      DRF ValidationError raised with a message string: the body
                      is a bare JSON array of error messages.
                  - type: object
                    additionalProperties:
                      oneOf:
                        - type: array
                          items:
                            type: string
                        - type: string
                    description: >-
                      Validation failure: a map of field name to a list of error
                      messages (DRF serializers) or a single message (e.g.
                      organization_id validation).
                  - type: object
                    properties:
                      error:
                        type: string
                    required:
                      - error
                    description: Hand-built application error body.
                description: >-
                  Bad request. The body is a bare array of messages, a
                  field-error map, or an {error} object depending on which
                  validation failed.
              examples:
                FieldValidationError:
                  value:
                    metadata:
                      - Invalid JSON string.
                  summary: Field validation error
                ValidationError:
                  value:
                    - Missing input key document
                  summary: Validation error
          description: Invalid request data or agent input validation error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetailResponse'
              examples:
                Forbidden:
                  value:
                    detail: Insufficient credits to start a new job
          description: >-
            Access to the Agents feature is forbidden, permission to access this
            agent denied, or insufficient credits
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetailResponse'
              examples:
                NotFound:
                  value:
                    detail: Not found.
                  summary: Not found
          description: Agent not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetailResponse'
          description: Internal error while running the agent
      security:
        - apiKeyAuth: []
components:
  schemas:
    AgentExecutionRequest:
      type: object
      description: >-
        Agent execution request. In addition to `metadata`, every key of the
        agent's input definitions is accepted as a property (text value or file
        upload).
      properties:
        metadata:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: >-
            Optional metadata stored as-is on the created agent job. A
            JSON-encoded object string is also accepted; null is treated the
            same as omitting the field (empty metadata). Only honored by the
            single-run endpoints — when this object is an item of the
            run-async-many `inputs` list, `metadata` is ignored.
      additionalProperties: true
    AgentDatum:
      type: object
      properties:
        key:
          type: string
          description: The key of the output
        description:
          type: string
          description: The description of the output
        data_type:
          type: string
          description: The MIME data type of the output
        value:
          type: string
          description: The value of the output, serialized as a string
        cost:
          type: number
          format: double
          description: The cost of the agent job execution
      required:
        - data_type
        - key
        - value
    ErrorDetailResponse:
      type: object
      description: 'DRF default error body: NotFound, PermissionDenied, Http404, etc.'
      properties:
        detail:
          type: string
          description: Human-readable error detail
      required:
        - detail
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        Organization API key passed as a Bearer token. This is the scheme used
        by the public SDK surface.

````