# Unified API Source: https://docs.settlemint.com/docs/architects/components/platform/unified-api The Unified API is the programmatic entry point for DALP asset, compliance, servicing, and settlement operations. It exposes versioned API documentation, authenticated routes, tenant-scoped data access, and consistent request and response contracts for integration teams. ## Overview [#overview] The Unified API lets you connect external systems to DALP platform operations without bypassing the controls that protect asset, compliance, servicing, and settlement workflows. The API is the programmatic counterpart to the Asset Console: requests authenticate the caller, resolve the relevant platform context, apply tenant scope where the route needs it, and return structured responses that integration code can handle. The API exposes versioned documentation and OpenAPI specifications. `/api/v2` serves the current interactive API explorer. `/api/v2/spec.json` serves the v2 OpenAPI document for client generation and external API tooling. `/api` redirects to the v2 explorer. ## What the API is for [#what-the-api-is-for] Use the Unified API when an integration needs to start, inspect, or automate DALP workflows from another system. Typical callers include issuer portals, back-office systems, compliance tooling, reporting pipelines, and controlled operational scripts. | Integration need | API role | Boundary | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | Asset lifecycle work | Start or inspect operations such as creation, servicing, transfer, mint, burn, or pause when the route supports that operation | The API does not remove approval, signing, compliance, or on-chain validation steps. | | Compliance and identity workflows | Read or update identity, claim, and compliance state through authenticated routes | The selected compliance provider, legal policy, and source evidence remain part of the operating model. | | Platform administration | Read configuration, health, activity, and system-level state exposed by versioned routes | Administrative routes still require the right caller permissions and platform context. | | External reporting | Pull indexed events, balances, assets, claims, and lifecycle data for downstream systems | Indexed reads reflect confirmed and processed platform state, not a promise that every upstream provider is healthy. | ## Request path [#request-path] The request path has four checkpoints. 1. For DALP operation routes, the caller uses the matching versioned API surface, such as `/api/v2` or a route listed in `/api/v2/spec.json`. Authentication flows are separate and use `/api/auth/*`. 2. Authenticated operation routes resolve the caller session and authorisation context before business logic runs. 3. Tenant-scoped routes bind database access to the caller's tenant and, where needed, the resolved system address and chain. 4. Route handlers use the path the endpoint needs: some read indexed platform state, some hand state-changing work to the execution layer, and some serve direct API work such as document download or bundler operations. This separation matters during incident review. A failed request can be an authentication failure, a tenant-scope mismatch, a validation error, a direct-handler failure, an execution failure, an on-chain revert, or a stale indexed read. Treat those as different problems rather than retrying every failure as if it were temporary. ## API documentation surfaces [#api-documentation-surfaces] Use the versioned endpoints for platform integration work. Auth flows are the exception: sign-in, session, and API-key routes live under `/api/auth/*`, not under a versioned `/api/v1` or `/api/v2` prefix. | Endpoint | Purpose | | ------------------- | ------------------------------------------------------------------------------- | | `/api/v2` | Interactive API explorer for the current v2 surface. | | `/api/v2/spec.json` | OpenAPI JSON document for v2 client generation and external API tooling. | | `/api/v1` | Interactive explorer for the v1 surface where legacy integrations still use it. | | `/api/v1/spec.json` | OpenAPI JSON document for v1 clients. | | `/api/auth/*` | Authentication flows such as sign-in, session, and API-key operations. | Choose the documented surface that matches the integration contract you operate. Use the auth surface for caller identity flows, then check the route scope before you design caller permissions. Routes use different scopes depending on the data or operation they expose. ## Route scopes [#route-scopes] | Scope | What it means | Use it for | | -------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Public | The route does not require an authenticated caller. | Health or public metadata routes where no tenant data is exposed. | | Authenticated | The route requires a resolved caller session and authorisation context. | User, account, and operational routes that depend on who is calling. | | Tenant scoped | The route constrains database access to the caller's tenant and scoped platform context. | Asset, identity, compliance, and lifecycle reads or mutations that must not cross tenants. | | System indexed | The route resolves system context and reads indexed platform state. | Activity, statistics, balances, and monitoring views backed by indexed chain and platform data. | When you design an integration, map each call to the narrowest scope that can do the job. Do not use administrative or global routes for tenant workflows that have a scoped route. ## Responses and errors [#responses-and-errors] API responses are structured for machine handling. Validation failures, authentication failures, authorisation failures, missing resources, rate limits, and server-side errors use distinct HTTP status classes so client code can make the right next move. | Category | HTTP status | Caller next step | | ---------------------- | ----------- | --------------------------------------------------------------------------------------------------------- | | Validation error | 400 | Fix the request shape, identifier, or field value before retrying. | | Authentication failure | 401 | Reauthenticate or refresh the caller credentials. | | Authorisation denied | 403 | Check the caller role, tenant, and platform permissions. | | Resource not found | 404 | Verify the identifier and the tenant or system context used for the request. | | Rate limited | 429 | Back off and retry after the advertised delay when provided. | | Server error | 500 | Retry only when the operation is safe to repeat. Escalate with the request context if the error persists. | For state-changing operations, check whether the route documents idempotency, execution status, or transaction tracking before retrying. A retryable transport error is not proof that the underlying operation did nothing. ## Integration checklist [#integration-checklist] Before connecting an external system to the Unified API: * Choose the versioned surface and generate or configure the client from the matching OpenAPI document. * Confirm the caller has the roles needed for the exact tenant and system context it will use. * Keep tenant identifiers, system addresses, chain IDs, and asset identifiers explicit in the integration design. * Treat indexed reads, direct API handlers, and state-changing execution as separate paths with separate failure handling. * Log request identifiers, route names, caller identity, tenant context, and response status in the external system. * Define retry behaviour per route, especially for state-changing operations that can reach signing or on-chain submission. ## See also [#see-also] * [API integration guide](/docs/developers/api-integration/getting-started) for implementation steps. * [Authentication](/docs/compliance-security/security/authentication) for caller identity and API key management. * [Asset Console](/docs/architects/components/platform/asset-console) for the web interface that uses the same platform workflows. * [DALP Execution Engine](/docs/architects/components/infrastructure/execution-engine) for operation coordination and transaction execution. * [Platform flows](/docs/architects/flows) for the path from request to execution, contract enforcement, and indexed evidence.