Skip to content

Add 23 endpoints from the current spec (Extract, billing, workspace consent) - #92

Open
kriton-dev wants to merge 1 commit into
ContextualAI:mainfrom
kriton-dev:add-missing-endpoints
Open

kriton-dev wants to merge 1 commit into
ContextualAI:mainfrom
kriton-dev:add-missing-endpoints

Conversation

@kriton-dev

Copy link
Copy Markdown

The OpenAPI spec at https://docs.contextual.ai/api-reference/openapi.json (version 1.0) has 66 endpoints and this SDK covers 40. This PR adds 23 of the other 26, following the generated code already in the repo: a params type and a response type for each endpoint, sync and async methods with the raw and streaming variants, entries in api.md, and tests in the existing pattern. They go on three new resources, client.extract (documents, jobs and schemas, including the document upload as multipart), client.billing and client.workspaces. Nothing that is already in the SDK is renamed or removed.

Endpoint New method
DELETE /extract/documents/{document_id} client.extract.delete_document()
DELETE /extract/schemas/{schema_id} client.extract.delete_schema()
GET /extract/documents client.extract.list_documents()
GET /extract/documents/{document_id} client.extract.retrieve_document()
GET /extract/jobs client.extract.list_jobs()
GET /extract/jobs/{job_id} client.extract.retrieve_job()
GET /extract/jobs/{job_id}/results client.extract.retrieve_job_results()
GET /extract/schemas client.extract.list_schemas()
GET /extract/schemas/{schema_id} client.extract.retrieve_schema()
POST /extract/documents/upload client.extract.upload_document()
POST /extract/jobs client.extract.create_job()
POST /extract/schemas client.extract.create_schema()
PUT /extract/jobs/{job_id}/results client.extract.update_job_results()
PUT /extract/schemas/{schema_id} client.extract.update_schema()
GET /billing/balance client.billing.retrieve_balance()
GET /billing/balance/top-ups client.billing.list_top_ups()
GET /billing/billing_mode/history client.billing.retrieve_billing_mode_history()
GET /billing/metadata client.billing.retrieve_metadata()
GET /billing/usages/acl client.billing.retrieve_acl_usage()
GET /billing/usages/earliest_date client.billing.retrieve_earliest_usage_date()
GET /billing/usages/monthly client.billing.retrieve_monthly_usage()
GET /workspaces/consent client.workspaces.retrieve_consent()
PUT /workspaces/consent client.workspaces.update_consent()

I left out three on purpose. GET /extract/jobs/{job_id}/stream is described as a stream of events but declares a JSON response, so how it should look in the SDK is your call. GET /agents/templates/acl and POST /agents/{agent_id}/query/acl carry the same summaries as agents.templates.list() and agents.query.create(), and the spec does not say how they differ. If any of the three should be in the SDK, say how and I will add them the same way.

The test suite cannot run as written any more: scripts/mock starts Prism from the openapi_spec_url in .stats.yml, and that Stainless bucket now answers NoSuchBucket. I ran it against the same Prism version the script pins, started on the live spec. I generated the code from the spec with my own generator, set up to match the Stainless output in this repo, and then read through the result. ruff check, ruff format --check, strict pyright and mypy, with the versions pinned in requirements-dev.lock, give the same results as main. Against the mock, 1705 tests pass (1229 on main), including the new endpoints' tests in the existing pattern. Two proxy environment tests fail on main and on this branch alike, because of my machine's proxy settings. 46 of the new tests sit in one file, tests/test_added_calls_stubbed.py, which calls every new method sync and async against a respx stub and checks the request method, path, body, query and headers against the spec, and that the documented response parses into the new type with strict validation on.

I found this repo while looking at SDKs that stopped getting updates when Stainless shut down its hosted service. The Node SDK, contextual-client-node, is missing the same 23 endpoints. Bringing it up to date and keeping both in sync with the API is paid work I do, and I would be glad to talk about it here. If a smaller review is easier, I can start with a PR of just billing and workspaces (9 endpoints), and send Extract after.

@kriton-dev kriton-dev changed the title feat(api): add 23 endpoints from the current spec Add 23 endpoints from the current spec (Extract, billing, workspace consent) Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant