How to Implement Endpoints for Asenion Assurance

This guide tells you how to implement the API endpoints so that Asenion Assurance (the test provider) can connect to your system and run compliance and security tests. Implement these endpoints on your side; Asenion Assurance will call them to send prompts and evaluate responses.

→ Quick start: See Client Checklist for a step-by-step checklist covering Custom Provider and Model testing.

API definition at a glance

Endpoint	Method	Purpose
`/chat`	`POST`	Send prompt(s), get assistant reply (required)
`/sessions`	`POST`	New session — create session, get `session_id` (optional)
`/sessions/{session_id}/restart`	`POST`	Restart session — clear state, same or new `session_id` (optional)
`/sessions/{session_id}`	`DELETE`	End session — invalidate session (optional)

Chat request body (JSON):

{
  "message": "string (required for single-turn)",
  "system": "string (optional)",
  "messages": [ { "role": "system|user|assistant", "content": "string" } ],
  "session_id": "string (optional)"
}

Chat response body (JSON):

{
  "content": "string (required)",
  "session_id": "string (optional)",
  "usage": { "prompt_tokens": 0, "completion_tokens": 0 }
}

New session — response (POST /sessions, 200):

{
  "session_id": "string (required)"
}

Restart session — response (POST /sessions/{session_id}/restart, 200):

{
  "session_id": "string (optional, same or new id)"
}

End session — response (DELETE /sessions/{session_id}): 200 with optional { "ok": true } or 204 No Content.

What Asenion Assurance Needs From You

To run tests, the provider (Asenion Assurance) must:

Send a user prompt (and optionally a system prompt or full conversation) to your API.
Receive your system’s reply as plain text (the “assistant” response).

You implement one required endpoint and, if your system is session-based, one optional endpoint. Use the request and response shapes below so Asenion Assurance can connect without custom adapter code.

Required: Chat Endpoint

Implement POST /chat (or POST /v1/chat — use a path that fits your API). This is the only required endpoint.

Request

Method: POST
Content-Type: application/json

Field	Type	Required	Description
`message`	string	Yes	The user prompt Asenion Assurance sends to your system.
`system`	string	No	System prompt or context (e.g. “You are a helpful assistant for X”). If omitted, use your default.
`messages`	array	No	Full conversation for multi-turn tests. Each item: `{ "role": "user" \\| "assistant" \\| "system", "content": "..." }`. Return the next assistant reply.
`session_id`	string	No	If you use sessions, the id from a previous response. Use it to continue the same conversation.

Example (single-turn):

{
  "message": "What are your guidelines on handling sensitive data?",
  "system": "You are a customer support assistant for a healthcare app."
}

Example (multi-turn with history):

{
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "What is 2 + 2?" },
    { "role": "assistant", "content": "2 + 2 is 4." },
    { "role": "user", "content": "Now multiply that by 10." }
  ]
}

Example (with session):

{
  "message": "Follow-up question from the user.",
  "session_id": "sess_abc123"
}

Response (success)

Status: 200 OK
Content-Type: application/json

Field	Type	Required	Description
`content`	string	Yes	The assistant’s reply. Asenion Assurance uses this for scoring and reports.
`session_id`	string	No	If you use sessions, return the session id so Asenion Assurance can send it on the next request.
`usage`	object	No	Optional token/cost metadata, e.g. `{ "prompt_tokens": 10, "completion_tokens": 20 }`.

Example:

{
  "content": "We only use sensitive data for the purposes you consented to, and we never share it with third parties for marketing.",
  "session_id": "sess_abc123"
}

Response (errors)

Return appropriate HTTP status and a JSON body when possible:

Status	When to use
`400`	Bad request (e.g. missing `message` when `messages` is not provided).
`401`	Missing or invalid authentication.
`500`	Server or model error.

Error body example:

{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}

Asenion Assurance will show the status and message when a test request fails.

cURL example: POST /chat

curl -X POST "https://api.yourcompany.com/chat" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "message": "What are your guidelines on handling sensitive data?",
    "system": "You are a customer support assistant for a healthcare app."
  }'

Expected response (200):

{
  "content": "We only use sensitive data for the purposes you consented to...",
  "session_id": "sess_abc123"
}

Session lifecycle (optional)

If your system is session-based, you can implement: new session (POST /sessions), restart session (POST /sessions/{session_id}/restart), and end session (DELETE /sessions/{session_id}). Asenion Assurance uses these for multi-turn or stateful tests.

1. New session — POST /sessions

Request

Method: POST
Content-Type: application/json

Body can be empty or include optional context, for example:

{
  "system": "You are a helpful assistant."
}

Response (success)

Status: 200 OK
Content-Type: application/json

Field	Type	Required	Description
`session_id`	string	Yes	Session or thread id to use in subsequent `POST /chat` requests.

Example:

{
  "session_id": "sess_xyz789"
}

If you don’t need sessions, you can skip this endpoint and only implement POST /chat. For single-turn tests, session_id is not required.

cURL example: POST /sessions

curl -X POST "https://api.yourcompany.com/sessions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"system": "You are a helpful assistant."}'

Expected response (200):

{
  "session_id": "sess_xyz789"
}

2. Restart session — `POST /sessions/{session_id}/restart`

Clear conversation state for this session and start fresh. The same session_id remains valid for subsequent /chat calls. Optionally return a new session_id if your implementation issues one on restart.

Request

Method: POST
Path: /sessions/{session_id}/restart
Content-Type: application/json

Path parameter: session_id — the session id from new session or from a chat response.

Body optional:

{
  "system": "Optional system prompt for the restarted session"
}

Response (200)

{
  "session_id": "sess_xyz789"
}

Return the same session_id or a new one. Use 404 if the session is not found or already ended.

cURL example:

curl -X POST "https://api.yourcompany.com/sessions/sess_xyz789/restart" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"system": "You are a helpful assistant."}'

3. End session — `DELETE /sessions/{session_id}`

Invalidate the session. After this, the session_id must not be used for /chat or /restart. Asenion Assurance may call this when a test run or conversation is finished.

Request

Method: DELETE
Path: /sessions/{session_id}

Path parameter: session_id — the session id to end. No body required.

Response

200 OK — optional body: { "ok": true }
204 No Content — no body
404 — session not found or already ended; optional body: { "error": "not_found", "message": "..." }

cURL example:

curl -X DELETE "https://api.yourcompany.com/sessions/sess_xyz789" \
  -H "X-API-Key: YOUR_API_KEY"

Authentication

Asenion Assurance will send credentials on every request. Support one or both of:

Bearer token
Header: Authorization: Bearer <your-token>
API key
Header: X-API-Key: <your-api-key>

Reject with 401 Unauthorized and a JSON error body when the token or key is missing or invalid. For local or internal use, you may allow unauthenticated access; for production, require auth.

Headers (request):

Content-Type: application/json
Authorization: Bearer <token>     # optional
X-API-Key: <key>                  # optional

Request/response schemas (reference)

Formal shapes your API must accept (request) and return (response).

POST /chat — request:

{
  "message": "string, required when messages is absent",
  "system": "string, optional",
  "messages": [
    { "role": "system | user | assistant", "content": "string" }
  ],
  "session_id": "string, optional"
}

POST /chat — response (200):

{
  "content": "string, required",
  "session_id": "string, optional",
  "usage": {
    "prompt_tokens": "number, optional",
    "completion_tokens": "number, optional",
    "total_tokens": "number, optional"
  }
}

POST /chat — response (4xx/5xx):

{
  "error": "string, e.g. bad_request | unauthorized",
  "message": "string, human-readable"
}

POST /sessions — request (body optional):

{
  "system": "string, optional"
}

POST /sessions — response (200):

{
  "session_id": "string, required"
}

POST /sessions/{session_id}/restart — request body (optional):

{
  "system": "string, optional"
}

POST /sessions/{session_id}/restart — response (200):

{
  "session_id": "string, optional (same or new id)"
}

DELETE /sessions/{session_id} — response (200 or 204):

No body required, or:

{
  "ok": true
}

How Asenion Assurance Uses Your Endpoints

Single-turn tests
Asenion Assurance sends POST /chat with message (and optionally system). Your API returns content. Asenion Assurance scores that reply (e.g. for compliance or security).
Multi-turn tests
Asenion Assurance sends POST /chat with messages (full conversation). Your API returns the next assistant reply in content. Asenion Assurance may repeat this for several turns.
Session-based tests If you implement the session lifecycle, Asenion Assurance can: new session (POST /sessions) to get a session_id; send multiple POST /chat requests with that id; restart session (POST /sessions/{session_id}/restart) to clear state and continue; end session (DELETE /sessions/{session_id}) when the run or conversation is finished.
Base URL and path
The Asenion Assurance operator configures your base URL (e.g. https://api.yourcompany.com) and the path to the chat endpoint (e.g. /chat or /v1/chat). Ensure your API is reachable from where Asenion Assurance runs (your network or the internet, depending on who runs the tests).

Quick Implementation Checklist

POST /chat
- Accept JSON with message (required when messages is not sent).
- Optionally accept system, messages, and session_id.
- Return JSON with content (required).
- Return 4xx/5xx and optional { "error", "message" } on failure.
Session lifecycle (optional):
- New session — POST /sessions: return JSON with session_id.
- Restart session — POST /sessions/{session_id}/restart: clear state, return same or new session_id.
- End session — DELETE /sessions/{session_id}: invalidate session (200/204).
Authentication
- Accept Authorization: Bearer <token> and/or X-API-Key: <key>.
- Return 401 with a clear message when auth fails.
HTTPS
- Expose your API over HTTPS so Asenion Assurance can call it securely.
Document your base URL and path
- Tell the Asenion Assurance operator the exact base URL and path (e.g. https://api.yourcompany.com/v1/chat) and which auth method you use.

Example: Minimal Single-Turn Handler (pseudo-code)

POST /chat
  body = parse JSON request
  if body.message is missing and body.messages is missing:
    return 400, { "error": "bad_request", "message": "message or messages required" }
  if not valid_auth(request.headers):
    return 401, { "error": "unauthorized", "message": "Invalid API key" }
  reply = your_llm_or_backend(body.message or body.messages, body.system, body.session_id)
  return 200, { "content": reply }

Example provider template (Asenion Assurance side)

This repo includes a template provider that calls the standard API from Asenion Assurance. Use it as a starting point or as the built-in client for your target API.

File	Purpose
`plugins/example-custom-provider.js`	Promptfoo provider: calls `POST /chat` (and supports `session_id`). Copy and set `apiBaseUrl`, `chatPath`, `apiKeyEnv` to your API.
`providers/example_custom.yaml`	Provider config: references the module and sets base URL and env key. Duplicate and edit for your target.

Quick use: Copy providers/example_custom.yaml to a new file (e.g. providers/my_api.yaml), set config.apiBaseUrl to your base URL and config.apiKeyEnv to the env var holding your API key. Set that env var (e.g. ASENION_EXAMPLE_API_KEY) and select the provider in the Asenion Assurance UI. To customize the request (e.g. custom path or headers), copy plugins/example-custom-provider.js and adjust.

Reference

OpenAPI (full API definition): asenion-custom-provider-api.yaml — machine-readable OpenAPI 3.0 spec for all endpoints, schemas, and auth.
Connecting Asenion Assurance: CLIENT_INTEGRATION.md — what to provide (base URL, auth, provider config) so tests can run.

Once your endpoints match this contract, Asenion Assurance can connect and perform tests against your system.

How to Implement Endpoints for Asenion Assurance

API definition at a glance

What Asenion Assurance Needs From You

Required: Chat Endpoint

Request

Response (success)

Response (errors)

cURL example: POST /chat

Session lifecycle (optional)

1. New session — POST /sessions

Request

Response (success)

cURL example: POST /sessions

2. Restart session — POST /sessions/{session_id}/restart

3. End session — DELETE /sessions/{session_id}

Authentication

Request/response schemas (reference)

How Asenion Assurance Uses Your Endpoints

Quick Implementation Checklist

Example: Minimal Single-Turn Handler (pseudo-code)

Example provider template (Asenion Assurance side)

Reference

2. Restart session — `POST /sessions/{session_id}/restart`

3. End session — `DELETE /sessions/{session_id}`