---
title: "Make a Decision"
method: POST
path: "/api/v1/decide"
tags: ["decision"]
---

# Make a Decision

`POST /api/v1/decide`

## Request

- Base URL: `https://docs.thedrive.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.thedrive.ai/api/v1/decide`
- Auth: none declared

Make **one coherent decision** about a document (or pure context), guided by
explicit instructions and caller-supplied context.

Unlike `/analyze` — which researches each schema field independently — `/decide`
answers the whole schema in a single reasoning pass with tools (reading, search,
computation, vision) available on the way. Use it when the fields are facets of
one judgment: where to file a document, which branch a workflow should take,
what to rename a file.

**Request parts**:
- `instructions` (required): what decision to make and what makes it correct.
- `context` (optional): JSON array of `{"label": ..., "content": ...}` blocks —
  folder listings, sibling decisions, established facts. Authoritative for the decision.
- `schema` (required): typed schema of the decision fields.
- `file`/`url` (optional): the document. Omit both for context-only decisions.

**Response**: `data` (schema-shaped, enforced by structured outputs), per-field
`confidence`, a single `reasoning` string for the whole decision, and `sources`.

**Failures are errors**: provider overload returns `503` with `Retry-After`;
provider errors return `502`. A `200` always contains a real decision.

**Pricing**: 2 credits/page (min 5) for documents, 10 for websites, 5 for context-only.

## Headers

- `X-API-Key` string

## Response `200`

Successful Response

- DecideResponse: Response for /decide — ONE coherent decision over the whole schema. Unlike /analyze, `reasoning` is a single string and `sources` a single list: the fields are facets of one judgment, so they share one rationale. A failed decision is an HTTP error, never a null-with-zero-confidence.
  - `success` boolean
  - `data` object, required: Decision values keyed by field name
  - `confidence` object: Per-field confidence scores (0.0–1.0)
  - `reasoning` string: One coherent explanation of the decision as a whole
  - `sources` string[]: Quotes from the document/context that support the decision
  - `steps` AgentStepResponse[]: Agent tool-call trace. Empty unless include_steps=true.
    - `tool` string, required: Tool that was called
    - `args` object: Arguments passed to the tool
    - `result_preview` string: First 200 chars of the tool output
  - `filename` string, nullable: Original filename or URL (null for context-only decisions)
  - `content_type` string, nullable: Detected MIME type
  - `model_used` string, required: Model used for the decision
  - `text_length` integer: Length of extracted document text (0 for context-only)
  - `total_pages` integer: Total pages in the document (0 for non-paginated files)
  - `credits_used` integer: Credits consumed
  - `schema_format` 'typed': Schema format used for extraction/analysis.

## Other responses

- `400`: Invalid request
- `413`: File too large
- `422`: Validation Error
- `502`: AI provider failed (not retryable)
- `503`: AI provider overloaded (retry with backoff)

---

[API](https://skmtc.dev/thedrive/apis/the-drive-ai-api.md) · [All operations](https://skmtc.dev/thedrive/apis/the-drive-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thedrive/apis/the-drive-ai-api/revisions/ee4e32647ebf?raw)