Referencev1

Agent API reference

The same authenticated tool set, over two transports. New to this? Start with the BYO-agent guide for how to enable access and mint a token.

Base URL & authentication

All endpoints are served from the canonical host over HTTPS:

Base URLtext

https://www.diligio.co

Every request carries a Diligio agent token as a bearer credential. The token resolves to a specific user in a specific workspace; there are no separate API keys or client ids.

Required headerbash

Authorization: Bearer dgo_agent_...

One optional header is recorded in the audit log as a label and is never used for authorisation:

Optional headerbash

X-Agent-Identity: claude-opus-4-8/my-bot

Tokens act as a person

A token's effective permission is min(token level, the user's live role), re-resolved on every request. Both the workspace switch and the user's opt-in must be on or the call is refused. See Access levels.

REST endpoints

Three endpoints under /api/agent/v1. Tool calls return a uniform envelope: { "ok": true, "result": ... } on success, or { "error", "code" } with an HTTP status on failure.

Self-check

GET/api/agent/v1/me

Confirms the token works and reports the effective level plus the tools it grants. Good for a connection test.

Requestbash

curl -s https://www.diligio.co/api/agent/v1/me \
  -H "Authorization: Bearer $TOKEN"

200 responsejson

{
  "ok": true,
  "org_id": "8f3c...",
  "user_id": "a91b...",
  "role": "contributor",
  "level": "full",
  "agent": "claude-opus-4-8/my-bot",
  "tools": ["kb_search", "list_projects", "list_questions",
            "get_question", "write_answer", "set_question_status",
            "export_project"]
}

List tools

GET/api/agent/v1/tools

Returns the tools available to this token's level, each with its JSON-Schema input. Tools the level does not grant are omitted entirely.

200 response (truncated)json

{
  "tools": [
    {
      "name": "kb_search",
      "description": "Semantic-search the workspace knowledge base...",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "description": "Natural-language query..." },
          "limit": { "type": "integer", "description": "Max results (1-10, default 5)." }
        },
        "required": ["query"],
        "additionalProperties": false
      }
    }
  ]
}

Call a tool

POST/api/agent/v1/tools/{tool}JSON body = the tool's arguments

The request body is the tool's arguments as a JSON object (send {} for tools that take none). The result is whatever the tool returns, wrapped in the success envelope.

Requestbash

curl -s -X POST https://www.diligio.co/api/agent/v1/tools/kb_search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"data retention policy","limit":3}'

200 responsejson

{
  "ok": true,
  "result": [
    {
      "id": "0c2e...",
      "question": "What is your data retention policy?",
      "answer": "Customer data is retained for the contract term plus 30 days...",
      "category": "Data Governance",
      "similarity": 0.81
    }
  ]
}

MCP (JSON-RPC)

POST/api/mcpStreamable HTTP, JSON-RPC 2.0

The MCP endpoint is https://www.diligio.co/api/mcp. It is a self-contained MCP server over Streamable HTTP: one JSON response per POST (no server-initiated SSE). The bearer header is the same as REST. See the guide for a Claude Desktop config.

Supported methods: initialize, ping, tools/list, tools/call, and the notifications/* acknowledgements. The default protocol version is 2025-06-18; the server identifies as { "name": "diligio", "version": "1.0.0" }.

initializejson

POST /api/mcp
Authorization: Bearer dgo_agent_...

{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": { "protocolVersion": "2025-06-18" } }

tools/calljson

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "kb_search",
    "arguments": { "query": "encryption at rest" }
  } }

A tool result comes back as MCP content; tool-level failures are returned as content with isError: true (so the model can read the message) rather than a JSON-RPC error:

tools/call resultjson

{ "jsonrpc": "2.0", "id": 2, "result": {
    "content": [ { "type": "text", "text": "[ ... JSON ... ]" } ]
} }

A GET to /api/mcp returns 405 (there is no SSE stream). Auth failures during initialize return the REST-style { error, code } body with the matching HTTP status.

Tool reference

Every tool, its required level, input schema and an example. Read-only tokens are limited to kb_search.

kb_search · read-only

Semantic search over the workspace knowledge base of previously answered questions. Use the returned answers as grounding; do not invent facts beyond them.

Field	Type	Required	Notes
`query`	string	yes	Natural-language query. Max 2,000 characters.
`limit`	integer	no	Results to return, 1–10 (default 5).

Examplejson

// body
{ "query": "Do you support SSO?", "limit": 5 }

// result: array of hits
[ { "id": "...", "question": "...", "answer": "...",
    "category": "...", "similarity": 0.78 } ]

list_projects · full

Lists the DDQ / questionnaire projects visible to the user. No arguments.

Examplejson

// body
{}

// result
[ { "id": "...", "title": "Acme vendor DDQ", "client": "Acme",
    "status": "In Progress", "progress": 42,
    "created_at": "2026-06-01T10:00:00Z" } ]

list_questions · full

Field	Type	Required	Notes
`project_id`	string	yes	From list_projects.
`status`	string	no	Optional status filter, e.g. "Drafting".

Examplejson

// body
{ "project_id": "...", "status": "Drafting" }

// result
[ { "id": "...", "number": 12, "category": "Security",
    "question": "...", "answer": null, "ai_draft": "...",
    "status": "Drafting", "confidence": 0.0,
    "answered_by_agent": false, "assignee_id": null,
    "due_date": null } ]

get_question · full

Fetch a single question in full detail.

Examplejson

// body
{ "question_id": "..." }

// result
{ "id": "...", "project_id": "...", "number": 12,
  "category": "Security", "question": "...", "answer": "...",
  "ai_draft": "...", "status": "SME Review", "confidence": 0.0,
  "answered_by_agent": true, "assignee_id": "...",
  "approver_id": "...", "due_date": null }

write_answer · full

Write (or overwrite) a question's answer with text the agent composed. The answer is flagged agent-authored and enters the human review workflow.

Field	Type	Required	Notes
`question_id`	string	yes	—
`answer`	string	yes	Answer text. Max 100,000 characters.

Examplejson

// body
{ "question_id": "...", "answer": "Yes. Diligio supports SAML and OIDC SSO..." }

// result
{ "id": "..." }

set_question_status · full

Move a question through the review workflow. The same transition and role rules as a human in this role apply; finalising to Final is admin-only.

Field	Type	Required	Notes
`question_id`	string	yes	—
`new_status`	string	yes	Target status, e.g. "SME Review", "Pending human review", "Final".

Examplejson

// body
{ "question_id": "...", "new_status": "SME Review" }

// result
{ "id": "...", "status": "SME Review" }

export_project · full

Export a completed project to its source format and mark it Completed. A terminal action, reachable only by a full agent whose user is permitted to export.

Examplejson

// body
{ "project_id": "..." }

// result: the export descriptor (filename, format, location)

Errors

REST errors return { "error": "<message>", "code": "<code>" } with the HTTP status below. In MCP, auth errors surface the same way during initialize; tool failures come back as isError content.

Status	code	When
401	`missing_token`	No bearer token on the request.
401	`invalid_token`	Malformed, unknown or revoked token.
401	`revoked_token`	Token was explicitly revoked.
401	`expired_token`	Token passed its expiry.
403	`agent_mode_disabled`	The workspace switch is off.
403	`user_unavailable`	The token's user is no longer active in the workspace.
403	`user_disabled`	The user's per-user switch is off.
403	`forbidden`	The tool exceeds this token's level.
400	`invalid_input`	Missing/invalid arguments, or a non-JSON body.
405	`method_not_allowed`	GET on the MCP endpoint (POST only).
500	`internal_error`	Unexpected server error.

Limits

kb_search: query up to 2,000 characters; limit clamped to 1–10.
write_answer: answer up to 100,000 characters.
Tool calls (and MCP requests) run up to 60 seconds; long exports are designed to finish inside that window.
Tokens act through a short-lived user session that is refreshed transparently; you never manage it.

Guide

← Bring your own AI agent

Enable access, access levels, and connecting an agent.