Uh oh!
There was an error while loading. Please reload this page.
docs: add "Get started with the API" developer guide - #713
docs: add "Get started with the API" developer guide#713omid-aignostics wants to merge 3 commits into
Conversation
b00813d to
9a2dd6fCompareCodecov Report✅ All modified and coverable lines are covered by tests. |
arne-aignx
left a comment
There was a problem hiding this comment.
I tested your commands for the refresh token flow and it works as expected. Also confirmed that our refresh token timeouts are quite gracious and usable for that purpose.
One addition I'd suggest is to also provide a full script for a hello world example (login flow -> call me endpoint to confirm that the API access works). E.g. the user only provides the client ID as an input
| Sign objects in your own cloud storage, or use the bucket that comes with your organization. That bucket works with any S3-compatible tooling: `GET /v1/me` returns `organization.aignostics_bucket_name`, `aignostics_bucket_protocol`, and an `aignostics_bucket_hmac_access_key_id` / `aignostics_bucket_hmac_secret_access_key` pair. Use those two as access key and secret against the storage provider's S3 endpoint, with SigV4, to upload objects and sign download URLs from `boto3`, the AWS CLI, or your language's S3 client. Treat the secret like any other credential: it grants access to your organization's slides. | ||
| ## Analyze your slides with Atlas H&E-TME |
There was a problem hiding this comment.
I'd state here explicitly, that this example may get out of date, when newer applications versions are released or different applications are used.
Refer back to ## Find out what the application expects
There was a problem hiding this comment.
Done in 5bb151b — the submit section now opens with a callout:
⚠️ This example is specific to Atlas H&E-TME1.3.0. Artifact names, required metadata, and outputs differ from one application to the next, and can change when a new version of the same application is released. Read the version's own contract first — the Find out what the application expects section above — rather than copying this payload verbatim.
I referred back by section name rather than an anchor link, because myst_heading_anchors is not configured in docs/source/conf.py, so an in-page #find-out-what-the-application-expects link would render dead in the Sphinx build (and myst.xref_missing is suppressed, so it would fail silently).
Posted by Claude claude-opus-5 via Claude Code on behalf of Omid Kokabi
There was a problem hiding this comment.
Small correction to my reply above: the callout was tightened in 6e374c2 during an editing pass over the whole guide, so the final wording is
⚠️ This example is specific to Atlas H&E-TME1.3.0. Artifact names, metadata, and outputs differ per application and change between versions, so read the version's own contract — Find out what the application expects, above — instead of copying this payload.
Same substance, fewer words.
Posted by Claude claude-opus-5 via Claude Code on behalf of Omid Kokabi
| - `input_artifacts[].metadata_schema` — a JSON Schema for the per-slide `metadata`. Validate against it locally instead of guessing; it is versioned with the application, so it is the one source of truth for required fields. | ||
| - `output_artifacts[]` — the result files a successful slide produces, with their MIME types. | ||
| ## Give the platform access to your slides |
There was a problem hiding this comment.
Let's be explicit in this chapter.
The preferred method to provide this URL, is to store the whole slide image in a S3-compliant storage (e.g. AWS S3, Google Cloud Storage) and mint a signed URL with an expiry of at least seven days.. yada yada..
For convenience we provide such storage and the access key id and secret access key to upload objects and sign download URLs for each individual organization. yada yada
There was a problem hiding this comment.
Done in 5bb151b — rewrote the chapter to say it outright.
It now leads with the preferred method: store the whole slide image in S3-compliant object storage (AWS S3, GCS, anything speaking the S3 API) and mint a signed URL for it, with an expiry of at least seven days so the link outlives queueing. I added that seven days is also the SigV4 maximum, so it is effectively the number rather than a floor to exceed.
Then, explicitly as convenience: every organization gets a bucket from us plus the credentials to upload into it and sign download URLs from it. The four GET /v1/me fields are now a table (aignostics_bucket_name, aignostics_bucket_protocol, aignostics_bucket_hmac_access_key_id, aignostics_bucket_hmac_secret_access_key), followed by a copy-pasteable upload-and-presign example against https://storage.googleapis.com with --expires-in 604800.
Field names and the gs protocol value verified against bucket/_service.py and the OpenAPI OrganizationReadResponse schema.
Posted by Claude claude-opus-5 via Claude Code on behalf of Omid Kokabi
There was a problem hiding this comment.
Note: 6e374c2 tightened the prose in this chapter as part of an editing pass over the guide. The substance you asked for is unchanged — preferred method stated outright, the seven-day expiry, the four GET /v1/me fields as a table, and the upload-and-presign example — just with less padding around it.
Posted by Claude claude-opus-5 via Claude Code on behalf of Omid Kokabi
9a2dd6f to
16ac868Compare16ac868 to
136fec8Compareomid-aignostics
commented
Aug 13, 2026
Thanks for testing the refresh token flow — good to know the timeouts are comfortable for that purpose. Added the hello world script in 5bb151b, as a new Hello world, end to end subsection right after the authentication steps. Client ID is the only input: ./hello_aignostics.sh your-client-idIt starts the device flow, prints the link to open plus the user code to compare, polls while you approve it (handling On verification: I could not run the real device flow here (no production client ID), so I exercised the script against a stubbed Posted by Claude claude-opus-5 via Claude Code on behalf of Omid Kokabi |
6e374c2 to
3df15abCompareAdds a guide for developers calling the Platform API directly over HTTPS, for integrations in other languages or existing pipelines that do not depend on the Python SDK. Walks one full workflow with curl: authentication via the OAuth 2.0 device flow and refresh token grant (including what the tokens are and why authentication is tied to a user), reading an application version's input contract, making slides reachable through signed URLs, submitting an analysis, following per-slide progress through the run and item state model, downloading results, and the 30-day retention window. Closes with retry, idempotency and caching conventions. Links the guide from the docs index and the interface table in README. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> [skip:test:long_running]
- Spell out how to make slides reachable: store the slide in S3-compliant object storage and mint a signed URL valid for at least seven days, plus the bucket and HMAC credentials the platform provides per organization, with an upload-and-presign example. - Flag the submit example as specific to Atlas H&E-TME 1.3.0, since artifact names and metadata differ per application and version, and point back to reading the version contract first. - Add a hello-world script taking only a client ID: device flow login, then GET /v1/me to confirm API access. [skip:test:long_running] Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Cut ~300 words (18%) without dropping a fact or an example. The device flow was explained three times over — conceptually, then step by step, then as a script — so "How it works" now states what a token is and links RFC 8628, leaving the steps to show the calls. The user-code comparison rationale moves into Step 2, where the comparison happens. Remainder is line-level trimming of the submit, follow, download and conventions sections. Net effect: the guide is shorter than before the review feedback, with the storage table, version caveat and hello world script added. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3df15ab to
fb25520Compare
Adds a guide for developers who call the Platform API directly over HTTPS — integrations in another language, or existing pipelines that should not depend on the Python SDK.
Renders at
get_started_api.html, linked from the docs index and the interface table in README.What it covers
One full workflow with
curl:input_artifacts[].metadata_schemaoff an application version as the source of truth for per-slide metadata.GET /v1/me.POST /v1/runspayload.TERMINATEDdoes not mean "succeeded".Review notes
Two open questions worth a second opinion:
aignostics_bucket_hmac_access_key_id/..._secret_access_keyfromGET /v1/me, which lets API users drive the organization's bucket with any S3 client and no SDK. Useful, but it puts a long-lived organization-wide secret in front of readers — is that what we want in public docs?he-tme 1.3.0. Should they read as "latest" instead, so the guide does not age?Everything in the guide was verified against the OpenAPI document and the SDK's authentication code rather than assumed. Two fields I removed for that reason:
callback_contextand thesubmitted_byrun filter exist only in the regenerated1.6.0+devspec, not in the committed1.4.0— worth confirming what production runs before adding them back.🤖 Generated with Claude Code