---
title: "Run the agent"
method: POST
path: "/agent"
---

# Run the agent

`POST /agent`

## Request

- Base URL: `https://marqpdf.com/v1`
- URL: `https://marqpdf.com/v1/agent`
- Auth: HTTP bearer

Give a goal in plain words; the agent plans and runs MarqPDF operations on your files with the model you chose (pipeline "agent"), reading each result before the next step. output.text is its summary, output.files the files it hands back, output.steps every call it made. Each operation it runs counts as one. Counts as one operation when it succeeds.

## Request body

- object
  - `files` string[], required: File ids, in order.
  - `goal` string, required: What to do, e.g. 'make these scans searchable, merge them in date order and get the result under 2 MB'.
  - `max_steps` integer: Model turns before it stops.
  - `model` string: "marqpdf" (the default) or "provider/model" on a key you've added, e.g. "anthropic/claude-opus-5-5", "openai/gpt-5.1", "gemini/gemini-2.5-pro", "openrouter/…", "custom/…".
  - `wait` integer: Seconds to wait for the result before answering 202 with a job to poll. 0 = answer at once.
  - `webhook_url` string, uri: POSTed the finished job, signed with your webhook secret (MarqPDF-Signature).

## Response `200`

Finished: the job with its output

- Job
  - `object` 'job', required
  - `id` string, required
  - `operation` string, required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed', required
  - `created_at` string, date-time, required
  - `started_at` string, nullable
  - `finished_at` string, nullable
  - `input` object
    - `files` string[]
    - `options` object
  - `output` object, nullable
    - `files` File[]
      - `object` 'file', required
      - `id` string, required
      - `name` string, required
      - `size` integer, required
      - `content_type` string, required
      - `pages` integer
      - `created_at` string, date-time, required
      - `expires_at` string, date-time, required
      - `source` 'upload' | 'url' | 'job', required
      - `job` string
      - `download_url` string, uri, required: Works without a key for an hour.
    - `text` string
    - `text_truncated` boolean
    - `note` string
    - `data` object: extract: the data
    - `model` string: AI operations: the model that answered
    - `steps` object[]: Workflows and the agent: each step
  - `error` object, nullable
    - `code` string
    - `message` string
  - `webhook_url` string, nullable
  - `webhook` object, nullable

## Other responses

- `202`: Still running: poll GET /jobs/{id} (also in Location)
- `400`: Invalid request
- `401`: Missing or invalid API key
- `402`: Free plan's monthly operations used
- `404`: Unknown file or operation
- `410`: File expired (kept 24 hours)
- `429`: Rate limit or job queue full (see Retry-After)
- `502`: The operation failed; the body also carries the job

---

[API](https://skmtc.dev/marqpdf/apis/marqpdf-api.md) · [All operations](https://skmtc.dev/marqpdf/apis/marqpdf-api/llms.txt) · [OpenAPI document](https://skmtc.dev/marqpdf/apis/marqpdf-api/revisions/9f614f17df46?raw)