Skip to main content

API docs

Connect an agent, push your inventory, verify an evidence pack

Written for engineers and auditors. How a test is graded and what a pass rate means is on How we test.

01

Connect an agent

Vidimus reaches your agent through the interface it already exposes. Paste a request that already works (a curl command, for example), check that the agent answers one real message, then run the tests. There is nothing to install.

JSON over HTTP

When it is the right one
Your agent takes a JSON body and answers with JSON in the same call. Most internal agents are this.

JSON over HTTP, with tool calls in the reply

When it is the right one
As above, and the reply also lists the tools the agent called, which we record as evidence.

A2A agent

When it is the right one
An agent that publishes an A2A agent card (protocol 1.0, 0.3 or 0.2). We read the card and follow each task until it completes.

MCP server

When it is the right one
A Model Context Protocol server over HTTP. We list its tools and test what it does when they are called.

Streaming (server-sent events)

When it is the right one
Your agent streams its answer as server-sent events. We read the stream to the end before grading it.

Event or webhook (back-office agent)

When it is the right one
A back-office agent started by a queue message or a webhook rather than a chat turn.

Microsoft Direct Line (Copilot Studio)

When it is the right one
A Microsoft agent reached over Direct Line. We open a conversation, post the message and wait for the reply.

The seven wire protocols a test run speaks.

Multi-turn tests carry the conversation: message history, A2A context and Direct Line conversation.

None

When it is the right one
Anyone who knows the URL can call it. Common for an agent that is already behind a VPN or a private network.

Header

When it is the right one
A fixed value sent on every request. The most common shape for an internal endpoint.

API key in the address

When it is the right one
The key travels in the URL rather than in a header. How Azure Functions and API Management usually front an agent.

OAuth 2.0 client credentials

When it is the right one
A machine-to-machine client registered with your identity provider. Choose this if your gateway issues short-lived tokens.

Google service account

When it is the right one
A service-account JSON key, for agents that sit directly on a Google API.

Mutual TLS

When it is the right one
Your gateway requires a client certificate we present at handshake time. Upload the certificate we should use.

The six ways a test run can authenticate.

Credentials sit in a vault. Vidimus stores only their reference. A secret found in a pasted command is never saved unless you type it again.

Ready-made settings per platform, the platforms we add on request and the registry connectors are on Integrations.

02

What a test run sends

What your agent receives during a run and what Vidimus keeps.

Tests per run

What to expect
Up to 150. Above that, the plan is trimmed by severity and the trimmed tests are named.

Attempts per test

What to expect
10, so a run makes at most 1,500 attempts. A multi-turn attempt sends one message per turn, up to five, and Direct Line and A2A poll until the reply arrives.

Pace

What to expect
Bounded concurrency with a throttle per agent.

Stopping

What to expect
Any run can be cancelled at any time.

Typical duration

What to expect
28 tests and 280 attempts took 22 minutes in our reference run.

What is recorded

What to expect
Every prompt, reply and tool call the agent exposes is kept in the EU.

Tool calls

What to expect
Tool calls are read from the reply, the tool log or the event trace, and treated as ground truth over what the agent says. A call to a tool the agent never declared is a finding, and so is an action the agent’s words refused but its tool log shows it took.

Sub-agents

What to expect
Your orchestrator (LangGraph, AutoGen, CrewAI) can push traces to a webhook for each agent (section 06), and each trace is matched to the test that caused it.

The traffic of one test run and what is recorded.

03

Push agents from your inventory (API)

Push agents into the Vidimus inventory from your own CMDB or governance tool. Up to 500 agents and 2 MB per call.

POST /api/v1/registry/agents
Authorization: Bearer <organisation key>
Content-Type: application/json

{
  "agents": [
    {
      "external_id": "cmdb-4821",
      "name": "Claims triage assistant",
      "description": "Routes motor claims under 25 000 EUR.",
      "endpoint_url": "https://agents.example.com/claims",
      "protocols": [
        "http"
      ],
      "owner": "claims-ops@example.com",
      "region": "europe-west1"
    }
  ]
}

Authenticate with your organisation’s inbound key, sent as a bearer token. The key is issued on the Settings page of the platform under Connected registries. It is shown once and stored as a hash. Agents arrive as drafts: nothing a person has accepted is overwritten, and a change from your side opens an item to review.

Responses

202
Accepted. The body counts the agents accepted and rejected, lists the first 50 issues by row, and gives the id and status of the sync it started (below).
400
The body is not JSON, or no agent in it is valid. The issues are listed.
401
The bearer token is missing or is not an active inbound key.
413
The body is larger than 2 MB.
429
More than 30 pushes in a minute on this connection. Wait the number of seconds the Retry-After header gives, then send again.
500
The sync failed on our side. Send again later.
HTTP/1.1 202 Accepted

{
  "accepted": 1,
  "rejected": 0,
  "issues": [],
  "run_id": "…",
  "status": "ok"
}

The OpenAPI 3.1 document describes every field.

04

Verify an evidence pack

Give your auditor the PDF and its register line: the hash and the Ed25519 signature check offline against our published key. No account is needed, and the check itself makes no call to Vidimus.

Offline in four steps

  1. Compute the SHA-256 of the PDF, written as 64 hex characters. That text is what Vidimus signed.
  2. Take the pack’s line from the evidence register CSV, exported from the Evidence packs page: sha256, signing_key_id and signature_ed25519_hex.
  3. Take the public key whose kid equals signing_key_id from the published key list. Retired keys stay listed, so an older pack still verifies.
  4. Check the Ed25519 signature over the hex digest with that key.
sha256sum evidence-pack.pdf
printf '%s' "$(sha256sum evidence-pack.pdf | cut -d' ' -f1)" > digest.txt
echo '<signature_ed25519_hex>' | xxd -r -p > sig.bin
curl -s https://www.vidimus.fr/.well-known/vidimus-signing-keys.json > vidimus-signing-keys.json
jq -r '.keys[] | select(.kid == "<signing_key_id>") | .public_key_pem' vidimus-signing-keys.json > key.pem
openssl pkeyutl -verify -pubin -inkey key.pem -rawin -in digest.txt -sigfile sig.bin

With OpenSSL 3, jq and xxd. OpenSSL answers "Signature Verified Successfully". On macOS, use shasum -a 256 and Homebrew’s openssl@3: the LibreSSL that ships with macOS cannot check Ed25519.

You can also use Node 18 or later, run beside the PDF and a saved copy of the key list. It prints true.

const { createHash, createPublicKey, verify } = require('node:crypto');
const pdf = require('node:fs').readFileSync('evidence-pack.pdf');
const line = { sha256: '<sha256>', signing_key_id: '<signing_key_id>', signature_ed25519_hex: '<signature_ed25519_hex>' };
const { keys } = require('./vidimus-signing-keys.json');
const key = createPublicKey(keys.find((k) => k.kid === line.signing_key_id).public_key_pem);
const hex = createHash('sha256').update(pdf).digest('hex');
console.log(hex === line.sha256 && verify(null, Buffer.from(hex), key, Buffer.from(line.signature_ed25519_hex, 'hex')));

Try it first on a specimen pack signed the same way: the files are on the evidence pack page.

The fingerprint printed on the cover and on every page is a different value: it identifies the content, because a file cannot carry its own hash.

In the product

Signed-in members of the organisation can also have the platform recompute the hash and check the signature:

GET /api/evidence-pack/<reviewId>/verify?pack=<packId>

{
  "pack_id": "…",
  "pack_version": 2,
  "byte_size": 412873,
  "content_sha256": {
    "recorded": "9f2c…",
    "actual": "9f2c…",
    "matches": true
  },
  "fingerprint_sha256": "41ab…",
  "signature": {
    "status": "valid",
    "kid": "vidimus-pack-…",
    "value": "…"
  },
  "signed": true,
  "legacy": false,
  "ok": true
}

Reading the response

content_sha256.matches
The SHA-256 recomputed from the stored PDF equals the one recorded when the pack was generated.
signature.status
Either "valid" or "invalid". It is "absent" for a pack generated before packs were signed, and "unknown_key" when the key that signed it is no longer published.
signed
True only when the hashes match and the signature is "valid": the field to require when you need a signed pack.
legacy
True for a pack generated before hashes were recorded: there is nothing to compare it with, so ok is false.
ok
True when the hashes match and the signature is not "invalid". It is also true when the signature is "absent" or "unknown_key", so ok on its own never means the pack is signed: if you need a signed pack, require signed to be true.

Without a session the endpoint answers 401. A member who has not completed the two-factor step gets 403. A pack the caller cannot see, including any pack of another organisation, gets 404. An id that is not a valid identifier gets 400, and 502 means the stored file could not be read, so nothing was checked.

05

Evidence-pack format

There is one PDF per decision. It is written in the organisation’s language (English or French) and covers every regulation the agent was tested against. The regulation is quoted from its English text on EUR-Lex. The sections come in this order.

  1. Cover. The agent, the decision, the issue date and the version, the content fingerprint (repeated on every page) and how to check the signature.
  2. Executive summary. The AI Act classification, the Article 5 screening, the Article 50 duties, the counts of tests and document verdicts, and the decision. When the registration left scope open, it says what the run could not reach before any finding.
  3. Registration. What the agent does and its tools, data and audience as registered.
  4. Legal classification. Each basis with the article it rests on, and the operator role. The review priority is not printed.
  5. Controls evaluation. Each control with its evidence and reasoning, with reviewer overrides noted and the depth of each framework stated.
  6. Test run summary. The run’s counts and its date, the tests that failed or need review, and the tool calls observed.
  7. Per-obligation coverage. Each applicable obligation quoted verbatim, then each test with its prompt, the expected behaviour and one reply. A test that failed or needs review also gives the finding and the judge’s reasoning. Documents appear with the passages quoted. Obligations that do not apply to the agent are listed. Obligations that apply later are kept apart.
  8. Reviewer decision. The decision (Approved, Approved with conditions or Rejected), the conditions and the separation-of-duties statement.
  9. Audit trail. The events in order, with the status of the hash chain.
  10. Methodology appendix. The versions the pack was produced with (below).

The appendix names the judge’s prompt version, the test technique library and the obligation corpus. Each term links to its definition in the glossary.

A pack cannot be edited: a re-issue is a new version, and both stay in your evidence register. Every obligation carries the verbatim regulation text it came from, so a disagreement is about the law, not our summary.

The other records

The classification record and the Article 50 attestation are each hashed and versioned. The run report comes as a PDF and as a CSV per test or per attempt. The Article 4 AI-literacy record comes as CSV. The evidence pack is the one that is signed.

06

Every interface in one list

Everything a customer, an auditor or a program can reach, outside the product’s screens.

Endpoints

POST /api/v1/registry/agents
Push agents from your inventory (section 03) with the organisation’s bearer key.
GET /api/v1/openapi
The OpenAPI 3.1 document of the registry API.
POST /api/agents/<agentId>/telemetry
Sub-agent traces from your orchestrator. Each test request carries an X-Vidimus-Probe-Id header. Send that id back with the trace. The request is authenticated by a secret per agent, sent in X-Vidimus-Telemetry-Secret.
GET /api/evidence-pack/<reviewId>/verify
For signed-in members: recompute a pack’s hash and check its signature (section 04).
GET /.well-known/vidimus-signing-keys.json
All public signing keys including retired ones.

Files you can export

Evidence register (CSV)
Every pack and classification record version, with sha256, signing_key_id and signature_ed25519_hex, for an auditor’s own check.
Agent register (CSV)
Every agent with its AI Act classification, under stable column names for a GRC tool.
Article 4 AI-literacy record (CSV)
One line per agent, from the literacy questions of the registration.
Run report (PDF and CSV)
One run detailed per test or per attempt.

API access comes with a pilot. Request a pilot.