DEVELOPER QUICKSTART
Your first record.
Evidence you can inspect.
Connect your application using a project API key. Start with the standalone Python example in your workspace: no AI provider, wallet or SDK installation is needed.
Open your project connection guide →1. Create a project and submission key
In Settings, create a workspace and project, or join an existing workspace. In API keys, create a key with submission access. Save the secret in your application’s secret manager; it is shown once.
Ask a workspace administrator to set up the integration if you cannot create keys.
2. Copy your project’s example
Open API keys → Connect this project. The example contains your tenant and project references. Set these environment variables in the process that will run it:
ORVESSIAN_API_URL=https://api-prod.orvessian.com
ORVESSIAN_API_KEY=<your project submission key>For hosted TEST use https://api.orvessian.com with a TEST key. Never mix credentials between environments. Python 3.10 or newer is recommended. The example uses only the standard library.
3. Submit one synthetic record
Run the copied Python example. A successful first submission returns HTTP 201 and an accepted event ID. An identical retry returns the original acceptance; a changed record with the same identity is rejected.
Keep the original event object and timestamp when retrying after a lost response. A fresh execution of the quickstart creates another synthetic record.
4. Inspect evidence
Return to Overview to see the connection checklist update, or open Decisions and search for the printed event ID. Select View evidence. Acceptance, inclusion and signing are separate stages; acceptance does not mean a proof is ready yet.
Download the record and its available evidence. A valid signature supports integrity, not the correctness of the underlying decision. Free projects use signed receipts; optional external assurance is shown only when available.
Connect your application
Send structured metadata to POST /v1/events. Keep prompts, conversations, documents, tool arguments and responses in your own systems. Use opaque references to link records.
| Task | Python client |
|---|---|
| Record a run | record_run(...) |
| Record a linked outcome | record_outcome(...) |
| Register a deployment | register_agent(...), then heartbeat(...) |
| Submit an external alert | record_alert(...) |
The optional Python client and framework adapters are source-distributed alpha tooling. Use the standalone workspace example for the first-record path; use the official public repository for source, installation instructions and verification examples. Do not install an unverified similarly named package.
Rules configure detection where enabled; they are not events to submit on every run. Rule and incident administration requires an authorised workspace session, not an ingestion credential.
Troubleshooting
- 401 — credential rejected
- Check the environment, key expiry and revocation status.
- 403 — access denied
- Use submission scope and the project associated with the key.
- 409 — conflicting retry
- Reuse the exact original record, or use a new event ID for a new event.
- 429 — limit reached
- Respect Retry-After and retry with the same identity.
- No records visible
- Check the project, date range and search filters.
- No agents in the directory
- Recording activity does not automatically register a deployment.
Use Help & support in the workspace. Include the status code and event reference, never your API key.