EN
Documentation
Documentation/Build and operate

API and external agents

Use a shared, permission-aware operation contract through HTTP, MCP, or the CLI.

On this page

Authenticate a connection

Create a scoped agent credential through Roles and access, or complete the instance's enabled OAuth flow. The HTTP operation API requires an Authorization: Bearer header; an interactive browser session alone does not authorize these endpoints.

Set NONDRO_URL to your instance's full base URL, including any mount prefix, and supply NONDRO_TOKEN through your credential mechanism. Use HTTPS outside local development. The MCP endpoint is the same base URL followed by /mcp/, including the trailing slash.

Discover operations and retrieve context

GET /api/agent/tools returns the current caller's available operation names and input schemas. POST /api/agent/call/{operation} accepts an arguments object. Discover that catalog before constructing requests: permissions and enabled features affect the available contract.

The following calls list the tools and retrieve a bounded context pack. These operations use the shared deterministic service; they do not start a conversation with nondro's model.

bash
curl --fail-with-body \
  -H "Authorization: Bearer $NONDRO_TOKEN" \
  "$NONDRO_URL/api/agent/tools"

curl --fail-with-body \
  -H "Authorization: Bearer $NONDRO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"arguments":{"limit":10}}' \
  "$NONDRO_URL/api/agent/call/get_context"

Use exact references and bounded results

Search for catalog records, then pass the returned identifiers to read_definition or read_objects. Respect projected or partial definitions: agent authoring supports the declared object and relationship schemas, not every interactive catalog capability.

Follow returned cursors to retrieve additional pages. Cursors are tied to the connection, request, and effective permissions; changes can invalidate them. A bounded context pack is not a complete organization-wide snapshot, and a search with no visible results does not establish that a record is absent.

Mutations, retries, and the CLI

Mutations require an idempotency_key. For an uncertain response, retry the same key with identical arguments. Use a new key for a new intended change. Version-sensitive edits also require expected_version; a stale version must be reviewed instead of overwritten.

Creating or validating a draft does not promote it. Governed action proposals require the appropriate grants and a human decision. The installed nondro CLI uses the same HTTP contract and environment variables.

bash
nondro agent tools
nondro agent context