docs: add "Get started with the API" developer guide

[omid-aignostics]

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:

1. Authenticate — what an access token is, why authentication is tied to a user rather than a machine, the OAuth 2.0 device flow step by step, and the refresh token grant for unattended use.
2. Find out what the application expects — reading input_artifacts[].metadata_schema off an application version as the source of truth for per-slide metadata.
3. Give the platform access to your slides — signed URLs, and the S3-compatible HMAC credentials returned by GET /v1/me.
4. Analyze your slides with Atlas H&E-TME — the POST /v1/runs payload.
5. Follow the analysis — the run/item state model, and why TERMINATED does not mean "succeeded".
6. Download results — per-slide artifacts, incremental polling, the 30-day retention window.
7. Conventions — retries, idempotency, caching.

Review notes

Two open questions worth a second opinion:

• HMAC bucket credentials. The guide documents aignostics_bucket_hmac_access_key_id / ..._secret_access_key from GET /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?
• Version pinning. Examples pin 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_context and the submitted_by run filter exist only in the regenerated 1.6.0+dev spec, not in the committed 1.4.0 — worth confirming what production runs before adding them back.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.
see 8 files with indirect coverage changes

[arne-aignx]

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

[omid-aignostics]

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-id

It starts the device flow, prints the link to open plus the user code to compare, polls while you approve it (handling authorization_pending and backing off on slow_down), and then calls GET /v1/me and prints your email, organization and bucket — so a successful run is proof the API access works. It also surfaces the refresh token so you can store it and skip the browser next time. curl and jq are the only dependencies, ~30 lines.

On verification: I could not run the real device flow here (no production client ID), so I exercised the script against a stubbed curl replaying Auth0's responses, covering the happy path, authorization_pending, slow_down, an expired_token failure, and the missing-argument case — all behave correctly. Worth one real run with a live client ID before merge if you have one handy. The GET /v1/me field paths (.user.email, .organization.display_name, .organization.aignostics_bucket_name) are verified against the OpenAPI schema, and the docs build renders the new sections cleanly.

---

Posted by Claude claude-opus-5 via Claude Code on behalf of Omid Kokabi

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud