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

# Create a run

> Submit a prompt to trigger an async canvas run. Agents orchestrate a
DAG of blocks to satisfy the prompt; poll `GET /v1/run/{run_id}`
until status becomes `completed`, `partial`, or `failed`.


<Card title="Try this in the developer playground" icon="play" href="https://platform.getspine.ai/playground" horizontal>
  Async runs need an API key and typically take 10–20 minutes (up to 2 hours
  for complex research). Get \$5 of free credits on signup — no subscription,
  \$1 = 1,000 credits. The developer playground handles auth, polling, and
  artifact downloads for you.
</Card>

<Note>
  For push notifications on run completion, configure a webhook endpoint in the [developer portal](https://portal.getspine.ai/webhooks) instead of using the per-run `webhook_url` field. See [Webhooks](/api-reference/concepts/webhooks) for the event schema and signature verification.
</Note>


## OpenAPI

````yaml POST /v1/run
openapi: 3.1.0
info:
  title: Spine API
  version: 1.0.0
  summary: The highest-quality research API — multi-agent canvas orchestration.
  description: |
    The Spine API delivers the highest-quality research available, ranked #1 on
    GAIA Level 3. Submit a prompt (with optional files, a template, or an
    explicit block configuration) to kick off an async multi-agent canvas run,
    and poll for the generated artifacts, DAG, and task tree.

    All endpoints are authenticated via the `X-API-KEY` header. Create a key
    from the [Spine developer portal](https://platform.getspine.ai).
  contact:
    name: Spine support
    email: support@getspine.ai
    url: https://platform.getspine.ai
servers:
  - url: https://api.getspine.ai
    description: Production
security:
  - apiKey: []
tags:
  - name: Runs
    description: Create and poll canvas runs.
  - name: Canvas
    description: Inspect the generated canvas DAG and task tree.
paths:
  /v1/run:
    post:
      tags:
        - Runs
      summary: Create a canvas run
      description: |
        Submit a prompt to trigger an async canvas run. Agents orchestrate a
        DAG of blocks to satisfy the prompt; poll `GET /v1/run/{run_id}`
        until status becomes `completed`, `partial`, or `failed`.
      operationId: createRun
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateRunRequest'
      responses:
        '200':
          description: Run accepted. Poll `poll_url` for status and results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateRunResponse'
              examples:
                accepted:
                  value:
                    success: true
                    data:
                      run_id: 550e8400-e29b-41d4-a716-446655440000
                      status: running
                      poll_url: /v1/run/550e8400-e29b-41d4-a716-446655440000
                      estimated_duration_ms: 900000
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      x-codeSamples:
        - lang: curl
          label: curl
          source: |
            curl -X POST https://api.getspine.ai/v1/run \
              -H "X-API-KEY: sk_spine_..." \
              -F "prompt=Summarize this sales data" \
              -F "template=memo" \
              -F "files=@sales-data.csv;type=text/csv"
        - lang: python
          label: Python
          source: |
            import requests

            response = requests.post(
                "https://api.getspine.ai/v1/run",
                headers={"X-API-KEY": "sk_spine_..."},
                data={"prompt": "Summarize this sales data", "template": "memo"},
                files={"files": ("sales-data.csv", open("sales-data.csv", "rb"), "text/csv")},
            )
            run = response.json()["data"]
            print(run["run_id"])
        - lang: javascript
          label: Node
          source: >
            import fs from "node:fs";


            const form = new FormData();

            form.set("prompt", "Summarize this sales data");

            form.set("template", "memo");

            form.append("files", new Blob([fs.readFileSync("sales-data.csv")]),
            "sales-data.csv");


            const res = await fetch("https://api.getspine.ai/v1/run", {
              method: "POST",
              headers: { "X-API-KEY": "sk_spine_..." },
              body: form,
            });

            const { data } = await res.json();

            console.log(data.run_id);
components:
  schemas:
    CreateRunRequest:
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
          description: What you want the agents to do.
          example: Create a Q1 performance report with charts
        template:
          allOf:
            - $ref: '#/components/schemas/Template'
          description: |
            Preset block configuration. Ignored when `blocks` is provided.
            Defaults to `auto`.
        blocks:
          type: string
          description: |
            JSON-encoded array of block types to override the template, e.g.
            `["document-block","table-block","image-block"]`. Precedence:
            `blocks` > `template` > `auto`.
          example: '["document-block","table-block","web-block"]'
        agent_instructions:
          type: string
          description: |
            Behavioral guidance applied across all agent layers (tone, rigor,
            audience, citation requirements, etc.).
          example: Write for a C-suite executive audience. Cite all sources.
        webhook_url:
          type: string
          format: uri
          description: Reserved for future webhook delivery — not yet honored.
        files:
          type: array
          description: |
            Optional file attachments. Images (PNG, JPEG, GIF, WEBP, SVG)
            become image-blocks; documents (PDF, DOCX, XLSX, CSV, TXT, MD,
            YAML, JSON, ZIP) become indexed file-blocks.
          items:
            type: string
            format: binary
    CreateRunResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          required:
            - run_id
            - status
            - poll_url
          properties:
            run_id:
              type: string
              format: uuid
            status:
              $ref: '#/components/schemas/RunStatus'
            poll_url:
              type: string
              description: Relative URL to poll for status.
            estimated_duration_ms:
              type: integer
              description: |
                Heuristic duration estimate in milliseconds. Runs typically take
                10–20 minutes; complex research can take up to 2 hours.
    Template:
      type: string
      description: Preset that controls which block types agents are allowed to create.
      enum:
        - auto
        - deep_research
        - report
        - slides
        - memo
        - excel
        - app
        - landing_page
    RunStatus:
      type: string
      enum:
        - running
        - completed
        - partial
        - failed
    Error:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: string
          description: Human-readable error message.
  responses:
    BadRequest:
      description: Malformed request (bad template, blocks, or UUID).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalidTemplate:
              value:
                success: false
                error: >-
                  Invalid template: foo. Valid templates: app, auto,
                  deep_research, excel, landing_page, memo, report, slides
    Unauthorized:
      description: Missing, invalid, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingKey:
              value:
                success: false
                error: X-API-KEY header required
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: |
        An API key from the Spine developer portal. Keys are prefixed with
        `sk_spine_` and shown only once at creation. Keep them server-side.

````