decision

Make a Decision

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.

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

Headers

X-API-Keystring

Response

Successful Response

successboolean
dataobject required

Decision values keyed by field name

confidenceobject

Per-field confidence scores (0.0–1.0)

reasoningstring

One coherent explanation of the decision as a whole

sourcesstring[]

Quotes from the document/context that support the decision

filenamestring nullable

Original filename or URL (null for context-only decisions)

content_typestring nullable

Detected MIME type

model_usedstring required

Model used for the decision

text_lengthinteger

Length of extracted document text (0 for context-only)

total_pagesinteger

Total pages in the document (0 for non-paginated files)

credits_usedinteger

Credits consumed

schema_format'typed'

Schema format used for extraction/analysis.

Example response

{
  "confidence": {
    "destination_path": 0.92
  },
  "content_type": "application/pdf",
  "credits_used": 5,
  "data": {
    "destination_path": "billing/Acme Corp/2026/Apr"
  },
  "filename": "invoice.pdf",
  "model_used": "gpt-5.1",
  "reasoning": "The invoice names Acme Corp and is dated April 2026; the instruction files by client, then year, then month, and 'billing/Acme Corp' already exists in the provided folder list.",
  "sources": [
    "Bill To: Acme Corp",
    "Invoice Date: April 3, 2026"
  ],
  "success": true,
  "text_length": 3200,
  "total_pages": 2
}

Changes

No recorded changes to this operation across all 1 revision of this API.