Account and emitter API

Product API calls from your session use your session token; calls from your agents use emitter signatures. This page covers the account-level endpoints you use to manage emitters programmatically. All paths are relative to https://app.provantix.tech.

Authentication

Session calls take your bearer token:

authorization: Bearer <session token>

Session tokens are issued by sign-in, last 30 days, and are held in memory only. A 401 anywhere means the session expired: sign in again.

Emitters

Register

curl -X POST /api/account/emitters \
  -H "authorization: Bearer <token>" -H "content-type: application/json" \
  -d '{"name":"prod"}'

Returns 201 with emitter_id, tenant_id, connector_instance, batches_endpoint, public_key_pem, and, for platform-generated keys, the one-time private_key_pem.

Bring your own key instead:

-d '{"name":"prod","public_key_pem":"-----BEGIN PUBLIC KEY-----\n…"}'

List

curl /api/account/emitters

Returns every emitter with status (active or revoked), registered_at, last_batch_seq and records_shipped.

Revoke

curl -X DELETE /api/account/emitters/emi_01m…

Marks the emitter revoked. Ingest rejects it with 403 from this point. Historical batches stay verifiable.

Delete (revoked, no history)

curl -X DELETE "/api/account/emitters/emi_01m…?purge=1"

Hard-deletes a revoked emitter that never shipped a batch. Refused with 409 when batches exist.

Setup summary

curl /api/account/setup

Everything the onboarding UI shows: organization, ingest endpoint, tenant id, emitter list, and SDK install notes. Useful for rendering your own onboarding flow.

Agents

curl -X POST /v1/agents \
  -H "authorization: Bearer <token>" -H "content-type: application/json" \
  -d '{"display_name":"Support Copilot","vendor":"acme","vendor_agent_id":"support-copilot"}'

Creates the agent record that attributes incoming telemetry at 0.95 confidence by vendor + vendor_agent_id.

Error shape

{ "error": "short machine-readable message" }