{"openapi":"3.1.0","info":{"title":"LangParse API","version":"1.0.0","description":"Parse documents into structured, validated JSON — and configure your account headlessly. Authenticate with an API key (`Authorization: Bearer <key>` or `X-Api-Key`).\n\n**Key scopes** — a key carries one or more:\n- `parse` — submit documents + read results (the **Parse** endpoints under `/api/v1`).\n- `manage` — create/edit models, routers, sources, destinations (the **Management** endpoints under `/api`).\n- `admin` — manage + API keys, members, billing.\n\nNew keys default to `parse` only. Management endpoints also accept a logged-in user session.\n\n**Uploading a file** — two ways:\n1. **Inline base64** — `POST /v1/models/{modelId}/parse` with JSON `{ fileBase64, fileName }` (one request, up to ~12 MB).\n2. **Presigned** (recommended, no size limit) — `POST /v1/models/{modelId}/uploads` to get a one-time S3 URL, `PUT` the raw file to it, then `POST /v1/models/{modelId}/parse` with `{ sourceKey }`.\n\nThen poll `GET /v1/documents/{documentId}` for the structured result."},"servers":[{"url":"https://api.langparse.dev"}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"tags":[{"name":"Parse","description":"Submit documents + fetch results. Requires a `parse`-scoped key."},{"name":"Management","description":"Configure models, routers, sources, destinations. Requires a `manage`-scoped key (or login)."}],"paths":{"/api/v1/models/{modelId}/parse":{"post":{"summary":"Parse a document","operationId":"parseDocument","tags":["Parse"],"parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Provide `fileBase64` (inline) OR `sourceKey` (from /uploads).","content":{"application/json":{"schema":{"type":"object","properties":{"fileBase64":{"type":"string","format":"byte","description":"Base64-encoded file bytes (≤ ~12 MB). Provide this OR sourceKey."},"sourceKey":{"type":"string","description":"Key from POST /uploads after you PUT the file to its URL. No size limit."},"fileName":{"type":"string","example":"invoice.pdf"}}}}}},"responses":{"202":{"description":"Parse job accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseAccepted"}}}},"401":{"description":"Missing or invalid API key"},"404":{"description":"Model not found"}}}},"/api/v1/models/{modelId}/uploads":{"post":{"summary":"Get a presigned upload URL","description":"Returns a one-time S3 URL. PUT the raw file bytes to it, then call POST /models/{modelId}/parse with the returned { sourceKey }. No size limit.","operationId":"createUpload","tags":["Parse"],"parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","example":"invoice.pdf"},"contentType":{"type":"string","example":"application/pdf"}}}}}},"responses":{"200":{"description":"Presigned upload ticket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadTicket"}}}},"401":{"description":"Missing or invalid API key"},"404":{"description":"Model not found"}}}},"/api/v1/documents/{documentId}":{"get":{"summary":"Fetch a parse result","operationId":"getDocument","tags":["Parse"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Document status and (when processed) structured result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResult"}}}},"401":{"description":"Missing or invalid API key"},"404":{"description":"Document not found"}}}},"/api/models":{"get":{"tags":["Management"],"summary":"List models","operationId":"listModels","responses":{"200":{"description":"Models","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}}}}},"post":{"tags":["Management"],"summary":"Create a model","operationId":"createModel","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelInput"}}}},"responses":{"200":{"description":"Created model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Model"}}}}}}},"/api/models/{modelId}":{"get":{"tags":["Management"],"summary":"Get a model","operationId":"getModel","parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Model"}}}},"404":{"description":"Not found"}}},"put":{"tags":["Management"],"summary":"Update a model (schema, strategy, output tags…)","operationId":"updateModel","parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelInput"}}}},"responses":{"200":{"description":"Updated model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Model"}}}}}}},"/api/routers":{"get":{"tags":["Management"],"summary":"List routers","operationId":"listRouters","responses":{"200":{"description":"Routers","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Router"}}}}}}},"post":{"tags":["Management"],"summary":"Create a router","operationId":"createRouter","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterInput"}}}},"responses":{"200":{"description":"Created router","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Router"}}}}}}},"/api/sources/policy":{"post":{"tags":["Management"],"summary":"Generate the cross-account IAM policy for an S3 source","operationId":"sourcePolicy","description":"Returns the trust + permission policy to create in YOUR AWS account before wiring an S3 bucket as a source.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceSpec"}}}},"responses":{"200":{"description":"IAM policy documents","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/sources":{"get":{"tags":["Management"],"summary":"List sources","operationId":"listSources","responses":{"200":{"description":"Sources","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}}}}},"post":{"tags":["Management"],"summary":"Create a source (managed inbox or your S3 bucket)","operationId":"createSource","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceInput"}}}},"responses":{"200":{"description":"Created source (+ S3 notification config for BYO buckets)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/destinations":{"get":{"tags":["Management"],"summary":"List destinations","operationId":"listDestinations","responses":{"200":{"description":"Destinations","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Destination"}}}}}}},"post":{"tags":["Management"],"summary":"Create a destination (webhook / S3 / SQS / SNS)","operationId":"createDestination","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationInput"}}}},"responses":{"200":{"description":"Created destination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Destination"}}}}}}},"/api/apikeys":{"post":{"tags":["Management"],"summary":"Create an API key (requires admin)","operationId":"createApiKey","description":"The secret is returned ONCE. `scopes` default to [\"parse\"]; granting manage/admin needs the admin role.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["parse","manage","admin"]}}}}}}},"responses":{"200":{"description":"New key (secret shown once)","content":{"application/json":{"schema":{"type":"object","properties":{"keyId":{"type":"string"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"secret":{"type":"string"}}}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-Api-Key"},"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ParseAccepted":{"type":"object","properties":{"documentId":{"type":"string"},"status":{"type":"string","enum":["queued"]},"debugId":{"type":"string"},"pollUrl":{"type":"string"}}},"UploadTicket":{"type":"object","properties":{"documentId":{"type":"string"},"sourceKey":{"type":"string"},"uploadUrl":{"type":"string","description":"PUT the raw file bytes here."},"method":{"type":"string","enum":["PUT"]},"expiresInSeconds":{"type":"integer"}}},"DocumentResult":{"type":"object","properties":{"documentId":{"type":"string"},"modelId":{"type":"string"},"status":{"type":"string","enum":["queued","processing","processed","failed"]},"debugId":{"type":"string"},"pageCount":{"type":"integer"},"data":{"type":"object","additionalProperties":true,"nullable":true},"fields":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/ExtractedField"}}}},"ExtractedField":{"type":"object","properties":{"name":{"type":"string"},"value":{},"confidence":{"type":"string","enum":["high","medium","low","flagged"]},"boxes":{"type":"array","items":{"$ref":"#/components/schemas/BoundingBox"}}}},"BoundingBox":{"type":"object","properties":{"left":{"type":"number"},"top":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"page":{"type":"integer"}}},"SchemaField":{"type":"object","properties":{"title":{"type":"string","example":"Invoice Number"},"name":{"type":"string","description":"Derived snake_case key (auto if omitted)."},"type":{"type":"string","enum":["text","number","date","boolean","select","list"]},"required":{"type":"boolean"},"transform":{"type":"string","description":"Per-field JS `(value, doc) => newValue`."},"children":{"type":"array","items":{"$ref":"#/components/schemas/SchemaField"},"description":"For list fields."}},"required":["title","type"]},"OutputTag":{"type":"object","description":"An S3 object tag projected from parsed data. Use ${data.field}, ${dest.uri/bucket/key} or literals.","properties":{"name":{"type":"string","example":"InvoiceTotal"},"expression":{"type":"string","example":"${data.invoice_total}"},"toSource":{"type":"boolean","description":"Tag the original source file (S3 sources)."},"toDestination":{"type":"boolean","description":"Tag the delivered output object."}},"required":["name","expression"]},"ModelInput":{"type":"object","properties":{"name":{"type":"string","example":"Invoice"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/SchemaField"}},"rule":{"type":"string","description":"Document validation JS `(doc, ctx) => void`."},"outputTags":{"type":"array","items":{"$ref":"#/components/schemas/OutputTag"}},"strategy":{"type":"object","additionalProperties":true,"description":"{ kind: single|consensus, extractors: [...], judge? }"}},"required":["name"]},"Model":{"type":"object","additionalProperties":true,"description":"A model (schema + strategy + output tags)."},"RouterInput":{"type":"object","properties":{"name":{"type":"string"},"candidates":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"[{ modelId, name, keywords[] }]"},"defaultModelId":{"type":"string"},"threshold":{"type":"number"},"extractSubDocuments":{"type":"string","enum":["none","page","boundaries","zonal"]}},"required":["name","candidates"]},"Router":{"type":"object","additionalProperties":true},"ResourceSpec":{"type":"object","properties":{"kind":{"type":"string","enum":["s3","sqs","sns"]},"mode":{"type":"string","enum":["source","destination"]},"resource":{"type":"string","description":"Bucket name / queue / topic ARN."},"region":{"type":"string"},"prefix":{"type":"string"}},"required":["kind","mode","resource"]},"SourceInput":{"type":"object","properties":{"kind":{"type":"string","enum":["s3-managed","s3"]},"name":{"type":"string"},"modelId":{"type":"string"},"routerId":{"type":"string"},"tagSourceFiles":{"type":"boolean","description":"Write the model's source-scoped output tags back onto each file."},"bucket":{"type":"string","description":"BYO (kind=s3) only."},"region":{"type":"string"},"prefix":{"type":"string"},"roleArn":{"type":"string","description":"BYO (kind=s3) only — role created from /sources/policy."}},"required":["kind"]},"Source":{"type":"object","additionalProperties":true},"DestinationInput":{"type":"object","properties":{"kind":{"type":"string","enum":["webhook","s3","sqs","sns"]},"name":{"type":"string"},"resultShape":{"type":"string","enum":["full","data-only"]},"sourceIds":{"type":"array","items":{"type":"string"},"description":"Sources routed to this destination ('rest-api' for API-submitted docs)."},"writeTags":{"type":"boolean","description":"Attach output tags + metadata to delivered S3 objects."},"url":{"type":"string","description":"webhook only"},"secret":{"type":"string","description":"webhook HMAC secret"},"bucket":{"type":"string"},"prefix":{"type":"string"},"region":{"type":"string"},"roleArn":{"type":"string","description":"S3/SQS/SNS — role created from /destinations/policy."}},"required":["kind"]},"Destination":{"type":"object","additionalProperties":true}}}}