Skip to main content

​
REST API Reference

Nooterra exposes a REST API for programmatic access to the platform. The API follows the OpenAPI 3.0 specification and uses JSON-RPC conventions where applicable.

​
OpenAPI Specification

The full OpenAPI spec is generated by src/api/openapi.js via the buildOpenApiSpec() function. It includes complete request/response schemas, authentication requirements, and error codes.

​
Base URL

The API base URL is configurable. The spec accepts an optional baseUrl parameter.

​
Required Headers

All API requests require the following headers:
HeaderRequiredDescription
x-proxy-tenant-idYesTenant scope for the request (e.g., tenant_default)
x-nooterra-protocolYesClient protocol version (major.minor). Required in production.
x-request-idNoOptional request ID, echoed in responses
x-idempotency-keyVariesIdempotency key. Required on mutation endpoints; optional on reads. If reused, request body must match.

​
Endpoints

The following endpoint groups are defined in the OpenAPI spec:

​
Action Intents

MethodPathDescription
—/v1/action-intentsAction intent operations
—/v1/action-intents/{actionIntentId}Single action intent
—/v1/action-intents/{actionIntentId}/approval-requestsApproval requests for an action intent

​
Approvals

MethodPathDescription
—/v1/approval-requests/{requestId}Single approval request
—/v1/approval-requests/{requestId}/decisionsDecisions on an approval request

​
Agent Resolution

MethodPathDescription
—/v1/public/agents/resolveResolve agent identities

​
Execution Grants

MethodPathDescription
—/v1/execution-grants/{executionGrantId}Single execution grant
—/v1/execution-grants/{executionGrantId}/revokeRevoke an execution grant
—/v1/execution-grants/{executionGrantId}/evidenceEvidence for an execution grant
—/v1/execution-grants/{executionGrantId}/finalizeFinalize an execution grant

​
Receipts

MethodPathDescription
—/v1/receipts/{receiptId}Retrieve an execution receipt

​
Disputes

MethodPathDescription
—/v1/disputesList/create disputes
—/v1/disputes/{disputeId}Single dispute

​
Integrations

MethodPathDescription
—/v1/integrations/installInstall an integration
—/v1/integrations/{hostId}/revokeRevoke an integration

​
Federation

MethodPathDescription
—/v1/federation/invokeInvoke a federated action
—/v1/federation/resultGet federated action result

​
Analytics & Trust

MethodPathDescription
—/v1/tenants/{tenantId}/analyticsTenant analytics
—/v1/tenants/{tenantId}/trust-graphTenant trust graph
—/v1/tenants/{tenantId}/trust-graph/snapshotsTrust graph snapshots
—/v1/tenants/{tenantId}/trust-graph/diffTrust graph diff

​
Key Schema Types

The API defines several versioned schema types:
  • AuthorityEnvelope.v1 — Defines the full authority context for an agent action: actor, principal, purpose, capabilities, data classes, side effects, spend envelope, delegation rights, risk class, reversibility, and evidence requirements.
  • ApprovalRequest.v1 — Links an action to an authority envelope for human approval.
  • NooterraHumanApprovalDecision.v1 — Records a human’s approve/deny decision with binding context.
  • X402ExecutionProof.v1 — Cryptographic execution proof (supports groth16, plonk, stark protocols).

​
Error Handling

The API uses federation-aware error codes (defined in src/federation/error-codes.js). Standard HTTP status codes apply, with structured error responses: 
{
  "error": "Human-readable message",
  "code": "ERROR_CODE",
  "details": {}
}

​
SDK

The @nooterra/api-sdk package (packages/api-sdk/) provides a TypeScript/JavaScript client: 
import { NooterraClient } from "@nooterra/api-sdk";
Key exports:
  • NooterraClient — main API client
  • NooterraHttpParityAdapter — HTTP parity adapter
  • NooterraMcpParityAdapter — MCP parity adapter
  • fetchWithNooterraAutopay — x402 autopay fetch wrapper
  • verifyNooterraWebhookSignature — webhook signature verification
  • verifyNooterraWebhook — Express middleware for webhook verification

​
Webhook Verification

import express from "express";
import { verifyNooterraWebhookSignature } from "@nooterra/api-sdk";

app.post("/webhooks/nooterra", express.raw({ type: "application/json" }), (req, res) => {
  // Verify and process webhook
});

​
Note

This is a reference overview. The full OpenAPI specification with complete request/response schemas, HTTP methods, and parameter details is generated programmatically by buildOpenApiSpec() in src/api/openapi.js. Consult the generated spec for the authoritative, machine-readable API definition.