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

# Start agent run

> <Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Authenticate with a platform Bearer credential or full-access workspace key permitted to edit this app. Scoped workspace keys are not accepted. Shares 60 reads or 6 mutations per minute per credential. Responses include request and rate-limit headers; 429 includes Retry-After. Queue one execution of an immutable deployment against exact commits. A PR number additionally requires matching current PR commits. Runs continue after disconnect. Retry with the same Idempotency-Key to recover a run whose response was lost. The free developer preview allows 20 execution attempts per workspace per UTC day. Interrupted model work is not replayed automatically. Results expire after 30 days.



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/imported/agent-runs
openapi: 3.1.0
info:
  title: Base44 App Management API
  version: 1.0.0
servers:
  - url: https://app.base44.com
security:
  - PersonalAccessTokenAuth: []
paths:
  /api/apps/{app_id}/imported/agent-runs:
    post:
      summary: Start agent run
      description: >-
        <Info>This API is in beta. Endpoints, fields, and behavior may still
        change, so avoid depending on it in production.</Info>


        Authenticate with a platform Bearer credential or full-access workspace
        key permitted to edit this app. Scoped workspace keys are not accepted.
        Shares 60 reads or 6 mutations per minute per credential. Responses
        include request and rate-limit headers; 429 includes Retry-After. Queue
        one execution of an immutable deployment against exact commits. A PR
        number additionally requires matching current PR commits. Runs continue
        after disconnect. Retry with the same Idempotency-Key to recover a run
        whose response was lost. The free developer preview allows 20 execution
        attempts per workspace per UTC day. Interrupted model work is not
        replayed automatically. Results expire after 30 days.
      operationId: start_run_api_apps__app_id__imported_agent_runs_post
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-f0-9]{24}$
            description: The imported app whose connected repository the agent may read.
            examples:
              - 6820f3a4e7b91d003c45a1f1
            title: App Id
          description: The imported app whose connected repository the agent may read.
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 200
            pattern: ^[A-Za-z0-9_.:-]+$
            description: >-
              Reuse this key with identical inputs when retrying. Use a new key
              for a new operation.
            examples:
              - review-123-v1
            title: Idempotency-Key
          description: >-
            Reuse this key with identical inputs when retrying. Use a new key
            for a new operation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartRun'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResponse'
              example:
                id: 6820f3a4e7b91d003c45a1f3
                deployment_id: 6820f3a4e7b91d003c45a1f2
                status: queued
                base_sha: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
                head_sha: cccccccccccccccccccccccccccccccccccccccc
                source:
                  kind: github_pull_request
                  number: 12
                package_digest: >-
                  aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                created_date: '2026-10-30T00:00:00Z'
        '400':
          description: 'invalid_cursor: The cursor does not match this query.'
          content:
            application/json:
              examples:
                invalid_cursor:
                  summary: invalid_cursor
                  value:
                    error:
                      code: invalid_cursor
                      message: The cursor does not match this query.
                      details: {}
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
        '401':
          description: 'unauthenticated: Sign in with Bearer credentials.'
          content:
            application/json:
              examples:
                unauthenticated:
                  summary: unauthenticated
                  value:
                    error:
                      code: unauthenticated
                      message: Sign in with Bearer credentials.
                      details: {}
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
        '403':
          description: >-
            forbidden or access_revoked: App, credential or repository access
            denied.
          content:
            application/json:
              examples:
                forbidden:
                  summary: forbidden
                  value:
                    error:
                      code: forbidden
                      message: App or repository access denied.
                      details: {}
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
        '404':
          description: >-
            not_found: The app, deployment or run was not found or the developer
            preview is disabled.
          content:
            application/json:
              examples:
                not_found:
                  summary: not_found
                  value:
                    error:
                      code: not_found
                      message: Agent run not found.
                      details: {}
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
        '409':
          description: >-
            idempotency_conflict, deployment_disabled, repository_changed,
            review_unavailable or publication_unavailable: The request conflicts
            with the current resource.
          content:
            application/json:
              examples:
                idempotency_conflict:
                  summary: idempotency_conflict
                  value:
                    error:
                      code: idempotency_conflict
                      message: Use a new Idempotency-Key for different input.
                      details: {}
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
        '422':
          description: >-
            invalid_request or review_too_large: Invalid request, or the
            rendered review exceeds the 60,000-byte publication limit.
          content:
            application/json:
              examples:
                invalid_request:
                  summary: invalid_request
                  value:
                    error:
                      code: invalid_request
                      message: The agent manifest is invalid.
                      details: {}
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
        '429':
          description: 'rate_limited: Retry after Retry-After seconds.'
          content:
            application/json:
              examples:
                rate_limited:
                  summary: rate_limited
                  value:
                    error:
                      code: rate_limited
                      message: Too many agent requests.
                      details: {}
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
        '503':
          description: >-
            Database temporarily unavailable (`database_unavailable`): the data
            cluster did not answer in time. Retry after the `Retry-After`
            seconds.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
              examples:
                database_unavailable:
                  summary: database_unavailable
                  value:
                    error:
                      code: database_unavailable
                      message: Database temporarily unavailable, please retry
                      details: {}
      security:
        - PersonalAccessTokenAuth:
            - full_access
        - WorkspaceApiKeyAuth:
            - full_access
        - WorkspaceApiKeyBearerAuth:
            - full_access
components:
  schemas:
    StartRun:
      properties:
        deployment_id:
          type: string
          pattern: ^[a-f0-9]{24}$
          title: Deployment Id
          description: The deployed agent version to run.
        base_sha:
          type: string
          pattern: ^[0-9a-f]{40}$
          title: Base Sha
          description: Exact base commit, never a branch name.
        head_sha:
          type: string
          pattern: ^[0-9a-f]{40}$
          title: Head Sha
          description: Exact head commit to analyze.
        source:
          anyOf:
            - $ref: '#/components/schemas/ChangeSource'
            - type: 'null'
          description: >-
            Optional change source whose current base and head must match.
            Required to publish a review.
      additionalProperties: false
      type: object
      required:
        - deployment_id
        - base_sha
        - head_sha
      title: StartRun
    RunResponse:
      properties:
        id:
          type: string
          title: Id
        deployment_id:
          type: string
          title: Deployment Id
        status:
          type: string
          enum:
            - queued
            - running
            - cancelling
            - cancelled
            - succeeded
            - failed
            - timed_out
          title: Status
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
        base_sha:
          type: string
          title: Base Sha
        head_sha:
          type: string
          title: Head Sha
        source:
          anyOf:
            - $ref: '#/components/schemas/ChangeSource'
            - type: 'null'
        package_digest:
          type: string
          title: Package Digest
        created_date:
          type: string
          title: Created Date
        started_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Started At
        finished_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Finished At
        result:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Result
          description: >-
            Validated output, source identity and coverage. Available for 30
            days. Never the full source snapshot.
        usage:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Usage
          description: >-
            Observed tokens, duration and provider cost where available. Null
            means unmeasured, not zero.
      type: object
      required:
        - id
        - deployment_id
        - status
        - error_code
        - base_sha
        - head_sha
        - source
        - package_digest
        - created_date
        - started_at
        - finished_at
        - result
        - usage
      title: RunResponse
    StandardErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/StandardError'
          description: What went wrong.
      type: object
      required:
        - error
      title: StandardErrorEnvelope
      description: The error body returned in the standard envelope.
    ChangeSource:
      properties:
        kind:
          type: string
          const: github_pull_request
          title: Kind
        number:
          type: integer
          minimum: 1
          title: Number
      additionalProperties: false
      type: object
      required:
        - kind
        - number
      title: ChangeSource
    StandardError:
      properties:
        code:
          type: string
          title: Code
          description: >-
            Stable machine-readable cause of the failure. Match on this, not on
            `message`.
          example: not_found
        message:
          type: string
          title: Message
          description: Human-readable explanation. It isn't a stable contract.
          example: App not found
        details:
          additionalProperties: true
          type: object
          title: Details
          description: >-
            Structured context for the failure, or an empty object when there's
            none.
          example: {}
      type: object
      required:
        - code
        - message
      title: StandardError
  securitySchemes:
    PersonalAccessTokenAuth:
      type: http
      scheme: bearer
      description: >-
        Personal access token, sent as `Authorization: Bearer <token>`. Each
        operation lists the permission it needs: `read_only` or `full_access`. A
        full-access token can call every operation. A read-only token can call
        only the operations that list `read_only`; anything else returns 403
        `read_only_credential_route_not_allowed`.
    WorkspaceApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: >-
        Workspace API key, sent as `api_key: <key>`. Each operation that accepts
        one lists what the key needs: a permission, `read_only` or
        `full_access`, like a personal access token, or a scope. A key without
        the scope gets 403 `workspace_api_key_scope_required`.
    WorkspaceApiKeyBearerAuth:
      type: http
      scheme: bearer
      description: >-
        Workspace API key, sent as `Authorization: Bearer <key>`. Accepted
        wherever `api_key` is, with the same permission.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.