API Reference
Conto publishes its REST API reference from the same OpenAPI source used by the in-app Swagger viewer. If you are onboarding a customer or integration partner, start with the interactive reference below and pair it with the authentication and operational guides in this page.Primary References
| Resource | URL | Best for |
|---|---|---|
| Interactive API docs | https://conto.finance/api-docs | Browsing endpoints and trying requests in Swagger UI |
| OpenAPI JSON | https://conto.finance/api/openapi | Code generation and schema validation |
| SDK guides | /sdk/installation | Agent-facing integration patterns and examples |
| Admin SDK guide | /sdk/admin | Organization-level automation with ContoAdmin |
| Error handling | /sdk/error-handling | Status codes, retryable failures, and recovery |
| Rate limits | /guides/rate-limits | Throughput planning and backoff strategy |
| Webhooks | /guides/webhooks | Event delivery, signatures, and retries |
Authentication
Use the credential type that matches the API surface you are calling:| Credential | Format | Use for | Notes |
|---|---|---|---|
| Browser session | Session cookie | Dashboard-originated /api/* requests | Used by the web app after login |
| Organization API key | conto_... | Org-level provisioning and management endpoints such as /api/agents, /api/wallets, /api/policies, and /api/api-keys | Works with ContoAdmin |
| Agent SDK key | conto_agent_... | Agent-facing /api/sdk/* endpoints | Works with the Conto client |
Base URLs
| Surface | URL |
|---|---|
| Production API base URL | https://conto.finance |
| Interactive reference | https://conto.finance/api-docs |
| OpenAPI spec | https://conto.finance/api/openapi |
| Public guides | https://conto.finance/docs |
Common Integration Paths
- Agent payment flow: Start with /sdk/payments for request, approval, execution, and status flows.
- Org provisioning and control-plane automation: Use /sdk/admin for agents, wallets, policies, and SDK key lifecycle management.
- External-wallet approval flows: Use /guides/external-approvals when Conto evaluates a payment but your infrastructure broadcasts the transaction.
- Service-to-service micropayments: Use /guides/x402-api-payments or /guides/mpp-session-payments for x402 and MPP flows.
Operational Expectations
POST /api/sdk/payments/requestsupportsidempotencyKeyfor safe client retries.- SDK keys always expire automatically: default lifetime is 365 days and the maximum is 730 days.
- Org API keys can be non-expiring unless you set
expiresInDayswhen creating them. - Webhook endpoints must be public HTTPS URLs and should verify Conto signatures on every request.
- Rate limits differ between SDK routes and dashboard routes; design clients to honor
429andRetry-After.