# authorship: generated by API Evangelist tooling. Stamped 2026-08-18
# on the file's own generator header (roadmap#64). An unmarked file is
# NOT assumed to be ours -- absence of evidence was never stamped.
x-method: generated
overlay: 1.0.0
info:
title: API Evangelist enhancements for the Lang.ai API
version: 1.0.0
extends: openapi/langai-api-openapi.yml
x-generated: '2026-07-19'
x-method: generated
x-source: https://docs.lang.ai/
x-note: >-
Lang.ai publishes no machine-readable specification, so openapi/langai-api-openapi.yml
was itself generated from the published reference. This overlay carries the API
Evangelist annotations layered on top of it — provenance, lifecycle posture, and the
agent-facing execution semantics captured in conventions/ and errors/.
actions:
- target: $.info
update:
x-apievangelist-slug: langai
x-apievangelist-artifacts:
conventions: conventions/langai-conventions.yml
errors: errors/langai-problem-types.yml
authentication: authentication/langai-authentication.yml
lifecycle: lifecycle/langai-lifecycle.yml
data-model: data-model/langai-data-model.yml
conformance: conformance/langai-conformance.yml
skills: skills/_index.yml
mcp: mcp/langai-mcp.yml
x-apievangelist-lifecycle-status: acquired
x-apievangelist-successor: https://capacity.com/
x-apievangelist-spec-provenance: >-
Generated by the API Evangelist enrichment pipeline from the human-readable
reference at https://docs.lang.ai/. Not published by Lang.ai.
- target: $.info
update:
x-rate-limit:
documented: true
numeric_limits_published: false
status_code: 429
headers: none documented
guidance: exponential backoff with jitter
- target: $.components.securitySchemes.bearerAuth
update:
x-token-rotation: >-
Single active token per instance — generating a new token invalidates previously
issued ones, so rotation is a hard cutover with no overlap window.
x-token-source: Settings section of the Lang.ai instance
- target: $.paths./documents.post
update:
x-idempotency:
supported: true
mechanism: client-supplied-resource-id
field: id
semantics: >-
Saving a document with an id that already exists overwrites it, so retries with a
stable client-supplied id are safe and will not duplicate.
header: null
- target: $.paths./project.post
update:
x-idempotency:
supported: false
warning: >-
Project creation has no idempotency contract — a blind retry after a timeout may
create a duplicate project. Reconcile with listProjects before retrying.
x-long-running:
note: >-
Project creation is asynchronous. The response returns only the new project id;
poll listProjects or getProjectTags until status transitions from Processing to
Completed (or Errored) before classifying against it.
- target: $.paths./analyze.post
update:
x-side-effects: none
x-note: >-
analyzeDocument classifies without persisting. Use saveDocument when the document
should land in the project's dashboard.
- target: $.tags
update:
x-apievangelist-note: >-
Tags in the OpenAPI sense (Projects, Documents) are unrelated to Lang.ai "tags",
which are the user-defined classifier groupings returned in responses.
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.