# Platform API Source: https://docs.settlemint.com/docs/architects/components/platform/platform-api The Platform 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 Platform API lets you connect external systems to DALP workflows for asset lifecycle operations, compliance processes, and settlement, without bypassing the controls that protect them. The Platform API is the programmatic counterpart to the Console. Each request authenticates the caller, resolves the relevant context, applies tenant scope where the route needs it, and returns a structured response that your integration code can act on. 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 Platform API when you need to start, inspect, or automate DALP workflows from another system. Typical callers include issuer portals, back-office systems, compliance tooling, reporting pipelines, and controlled 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: read-only handlers return indexed platform state, mutation handlers pass state-changing work to the execution layer, and direct handlers serve requests such as document download or bundler operations. This separation matters during incident review. A failed request can be an authentication problem, a tenant-scope mismatch, a validation error, a direct-handler fault, an execution failure, an on-chain revert, or a stale indexed read. Treat those as different problems rather than retrying every case as if it were temporary. ## API documentation surfaces [#api-documentation-surfaces] Use the versioned endpoints for platform integration work. Authentication flows are the exception: sign-in, session management, and API-key operations live under `/api/auth/*` rather than 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 scope before you design caller permissions. Each endpoint uses a scope that matches the data or operation it exposes. ## 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 endpoints for tenant workflows that have a scoped path. ## Responses and errors [#responses-and-errors] API responses are structured for machine handling. Validation errors, authentication failures, authorisation rejections, missing resources, rate limits, and server-side faults each use a distinct HTTP status class 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 Platform API: * Choose the versioned surface and generate or configure the client from the matching OpenAPI document. * Confirm your 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 your design. * Treat indexed reads, direct API calls, 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/api-reference/reference/getting-started) for implementation steps. * [Authentication](/docs/compliance-security/security/authentication) for caller identity and API key management. * [Console](/docs/architects/components/platform/console) for the web interface that uses the same platform workflows. * [DALP Workflow Engine](/docs/architects/components/infrastructure/workflow-engine) for operation coordination and transaction execution. * [Platform flows](/docs/architects/flows) for the path from request to execution, contract enforcement, and indexed evidence.