---
title: Endpoints | Docs | Lattix
description: "Reference for the eight /v1/sdk/* routes: discovery, planning, registration, and evidence ingestion."
source: "https://lattix.io/docs/api/endpoints/"
content-type: text/markdown
---

# Endpoints | Docs | Lattix

Platform API

# Endpoints

Reference for the eight /v1/sdk/\* routes: discovery, planning, registration, and evidence ingestion.

Every public Platform API operation is one of eight routes under `/v1/sdk/*`. This page documents each one: purpose, auth requirements, request body, and response body.

The same authenticated caller (tenant, principal, subject, scopes) resolves under `caller` in every response. That block is documented once in [Authentication → Caller identity on every response](https://lattix.io/docs/api/authentication/#caller-identity-on-every-response) and omitted from per-route response tables.

All routes return `application/json`. Error responses use the envelope documented under [Platform API → Error envelope](https://lattix.io/docs/api/#error-envelope). For exact schemas (especially nested `key_transport` and artifact-CID fields) use the [API Explorer](https://lattix.io/docs/api/explorer/) or the published OpenAPI document.

## Discovery routes

### capabilities

`GET /v1/sdk/capabilities`

Returns the resolved caller identity, active authentication mode, deployment-default scopes, and configured public platform domains. Call this at startup to discover what scopes each route requires.

**Auth:** bearer token. Some private deployments also enable a trusted-ingress mode.

**Response fields:**

| Field | Type | Notes |
| --- | --- | --- |
| `service` | string | Service name. |
| `status` | string | Typically `ready`. |
| `auth_mode` | enum | `trusted_headers`, `bearer_token`, or `bearer_token_or_trusted_headers`. |
| `auth_configuration` | object | Current public issuer, audience, and proof-of-possession contract. |
| `caller` | object | Resolved caller identity. |
| `default_required_scopes` | string\[\] | Deployment default scopes required on every route. |
| `routes` | array | Per-route capability: `route`, `domain`, `configured`, `required_scopes`. |

### whoami

`GET /v1/sdk/whoami`

Returns the resolved caller identity: tenant, principal, subject, scopes. Use it as a lightweight check that credentials are working.

**Auth:** bearer token. Some private deployments also enable a trusted-ingress mode.

**Response fields:**

| Field | Type | Notes |
| --- | --- | --- |
| `service` | string | Service name. |
| `status` | string | Typically `ok`. |
| `caller` | object | Resolved caller identity. |

### bootstrap

`GET /v1/sdk/bootstrap`

Describes the embedded-enforcement model. Call this once at application startup, cache the result, and use it to select operations and artifact profiles your deployment supports.

**Auth:** bearer token. Some private deployments also enable a trusted-ingress mode.

**Response fields:**

| Field | Type | Notes |
| --- | --- | --- |
| `service`, `status`, `auth_mode`, `auth_configuration`, `caller` | , | See above. |
| `enforcement_model` | string | The embedded-enforcement mode this deployment operates in. |
| `plaintext_to_platform` | boolean | Always `false` on supported deployments. |
| `policy_resolution_mode` | string | How this deployment resolves policy (for example, local or remote-resolve). |
| `supported_operations` | `ProtectionOperation[]` | Subset of `protect`, `access`, `rewrap`. |
| `supported_artifact_profiles` | `ArtifactProfile[]` | Subset of `tdf`, `envelope`, `detached_signature`. |
| `platform_domains` | array | Per-domain status: `domain`, `configured`, `reason`. |

## Protection routes

All protection routes share a common request shape that describes a workload and the resource being acted on. The platform returns a `decision` (allow / deny, required scopes) and an `execution` or `handling` block the caller uses to enforce locally.

Common request components:

| Component | Fields |
| --- | --- |
| `WorkloadDescriptor` | `application` (required), optional `environment` and `component`. |
| `ResourceDescriptor` | `kind` (required), optional `id`, `mime_type`. |
| `labels` | String array of caller-declared tags. |
| `attributes` | `{ string: string }` map of caller-declared attributes. |

### protection plan

`POST /v1/sdk/protection-plan`

Returns a local-enforcement plan for a proposed protect / access / rewrap operation. Metadata only; plaintext is explicitly out of contract.

**Auth:** bearer token. Some private deployments also enable a trusted-ingress mode.

**Request fields:**

| Field | Type | Notes |
| --- | --- | --- |
| `operation` | `ProtectionOperation` | `protect`, `access`, or `rewrap`. |
| `workload` | `WorkloadDescriptor` | Required. |
| `resource` | `ResourceDescriptor` | Required. |
| `preferred_artifact_profile` | `ArtifactProfile` | Optional preference; platform may override in `execution`. |
| `content_digest` | string | Optional; e.g. `sha256:...`. Absence is signalled on the response. |
| `content_size_bytes` | integer | Optional. |
| `purpose` | string | Optional free-text purpose. |
| `labels` | string\[\] | Caller tags. |
| `attributes` | string map | Caller attributes. |

**Response fields:**

| Field | Type | Notes |
| --- | --- | --- |
| `request_summary` | object | Normalized, sanitized view of the request the platform evaluated. |
| `decision.allow` | boolean | Whether the operation is authorized. |
| `decision.required_scopes` | string\[\] | Scopes that were required to authorize this operation. |
| `decision.handling_mode` | string | Caller-facing handling mode. |
| `decision.plaintext_transport` | string | Typically a "local-only" marker. |
| `execution.protect_locally` | boolean | Whether the SDK should perform the protection operation on the workload. |
| `execution.local_enforcement_library` | string | The enforcement library the SDK should invoke locally. |
| `execution.send_plaintext_to_platform` | boolean | Always `false` under the metadata-only stance. |
| `execution.send_only` | string\[\] | Metadata fields the SDK is expected to emit to the platform after local work. |
| `execution.artifact_profile` | `ArtifactProfile` | Profile to use when producing the artifact. |
| `execution.key_strategy` | string | Caller-facing key-handling strategy descriptor. |
| `execution.policy_resolution` | string | Caller-facing policy-resolution descriptor. |
| `execution.key_transport` | object | Optional key-transport guidance for managed-key or reference-based local flows. See the OpenAPI / Explorer for exact subfields. |
| `platform_domains` | array | Per-domain configured/reason flags. |
| `warnings` | string\[\] | Non-fatal advisories. |

### policy resolve

`POST /v1/sdk/policy-resolve`

Resolves authorization and handling guidance from metadata only. Useful when the caller wants a policy decision decoupled from a specific artifact profile or key workflow.

**Auth:** bearer token. Some private deployments also enable a trusted-ingress mode.

**Request fields:**

Same as `protection plan` except `preferred_artifact_profile` is not used.

**Response fields:**

| Field | Type | Notes |
| --- | --- | --- |
| `request_summary` | object | Normalized view of the request. |
| `decision.allow` | boolean | Allow or deny. |
| `decision.enforcement_mode` | string | Local enforcement mode descriptor. |
| `decision.required_scopes` | string\[\] | Scopes required for this decision. |
| `decision.policy_inputs` | string\[\] | Caller-facing list of policy inputs considered. |
| `decision.required_actions` | string\[\] | Required post-decision actions. |
| `handling.protect_locally` | boolean | Whether the caller should enforce locally. |
| `handling.plaintext_transport` | string | Transport marker for plaintext (always local-only). |
| `handling.bind_policy_to` | string\[\] | Identifiers the caller should bind the policy decision to. |
| `handling.evidence_expected` | string\[\] | Evidence events the caller should emit after enforcement. |
| `platform_domains`, `warnings` | , | As above. |

### key access plan

`POST /v1/sdk/key-access-plan`

Returns guidance for a wrap / unwrap / rewrap flow. The platform authorizes key use; the SDK performs the cryptographic work locally against the key access service.

**Auth:** bearer token. Some private deployments also enable a trusted-ingress mode.

**Request fields:**

| Field | Type | Notes |
| --- | --- | --- |
| `operation` | `KeyAccessOperation` | `wrap`, `unwrap`, or `rewrap`. |
| `workload`, `resource` | descriptors | Required. |
| `artifact_profile` | `ArtifactProfile` | Optional. |
| `key_reference` | string | Optional caller-provided reference to an existing key binding. |
| `content_digest` | string | Optional. |
| `purpose`, `labels`, `attributes` | , | Optional. |

**Response fields:**

| Field | Type | Notes |
| --- | --- | --- |
| `request_summary` | object | Normalized view of the request. |
| `decision.allow` | boolean | Allow or deny. |
| `decision.operation` | `KeyAccessOperation` | Echo of the requested operation. |
| `decision.required_scopes` | string\[\] | Scopes required. |
| `decision.key_reference_present` | boolean | Whether the caller supplied a key reference. |
| `execution.local_cryptographic_operation` | boolean | The SDK performs the cryptographic step locally. |
| `execution.platform_role` | string | Caller-facing platform role descriptor. |
| `execution.send_plaintext_to_platform` | boolean | Always `false`. |
| `execution.send_only` | string\[\] | Metadata the SDK is expected to emit. |
| `execution.artifact_profile` | `ArtifactProfile` | Profile to operate against. |
| `execution.authorization_strategy` | string | Caller-facing authorization-strategy descriptor. |
| `execution.key_transport` | object | Optional key-transport guidance for managed-key or reference-based local flows. See the OpenAPI / Explorer for exact subfields. |
| `platform_domains`, `warnings` | , | As above. |

## Registration

### artifact register

`POST /v1/sdk/artifact-register`

After the SDK has produced a protected artifact locally, this route registers its metadata with the platform. The platform tracks lifecycle without ever seeing the payload.

**Auth:** bearer token. Some private deployments also enable a trusted-ingress mode.

**Request fields:**

| Field | Type | Notes |
| --- | --- | --- |
| `operation` | `ProtectionOperation` | Typically `protect` or `rewrap`. |
| `workload`, `resource` | descriptors | Required. |
| `artifact_kind` | `ArtifactKind` | Optional; `data_object` or `tdf_manifest`. |
| `artifact_profile` | `ArtifactProfile` | The profile used to produce the artifact. Required. |
| `artifact_digest` | string | Cryptographic digest of the protected artifact. Required. |
| `artifact_cid` | string | Optional stable CID for the protected artifact or manifest. |
| `artifact_merkle_root_cid` | string | Optional root CID for multi-object or Merkle-tree artifacts. |
| `artifact_object_b64` | string | Optional base64-encoded **protected artifact bytes** when the caller wants platform-assisted CID derivation. Never send plaintext. |
| `artifact_locator` | string | Optional pointer to where the artifact is stored. |
| `decision_id` | string | Optional reference to the earlier decision this registration is bound to. |
| `key_reference` | string | Optional key binding reference. |
| `purpose`, `labels`, `attributes` | , | Optional. |

**Response fields:**

| Field | Type | Notes |
| --- | --- | --- |
| `request_summary` | object | Normalized view of the registration. |
| `registration.accepted` | boolean | Whether the registration was accepted. |
| `registration.required_scopes` | string\[\] | Scopes required. |
| `registration.artifact_transport` | string | Caller-facing transport descriptor. |
| `registration.send_plaintext_to_platform` | boolean | Always `false`. |
| `registration.catalog_actions` | string\[\] | Downstream catalog actions the platform will perform. |
| `registration.evidence_expected` | string\[\] | Evidence events the caller should emit after registration. |
| `platform_domains`, `warnings` | , | As above. |

## Evidence ingestion

### evidence

`POST /v1/sdk/evidence`

Records metadata-only evidence events associated with protected artifacts, policy decisions, and local enforcement outcomes. Ingested events land on the [Immutable Ledger](https://lattix.io/docs/concepts/immutable-ledger/).

**Auth:** bearer token. Some private deployments also enable a trusted-ingress mode.

**Request fields:**

| Field | Type | Notes |
| --- | --- | --- |
| `event_type` | `EvidenceEventType` | `protect`, `access`, `rewrap`, or `deny`. |
| `workload`, `resource` | descriptors | Required. |
| `artifact_kind` | `ArtifactKind` | Optional; `data_object` or `tdf_manifest`. |
| `artifact_profile` | `ArtifactProfile` | Optional. |
| `artifact_digest` | string | Optional digest of the artifact this event concerns. |
| `artifact_cid` | string | Optional stable CID for the artifact or manifest this event concerns. |
| `artifact_merkle_root_cid` | string | Optional root CID for multi-object or Merkle-tree artifacts. |
| `decision_id` | string | Optional reference to the decision this event ties back to. |
| `outcome` | string | Optional caller-facing outcome descriptor. |
| `occurred_at` | string | Optional RFC 3339 timestamp. |
| `purpose`, `labels`, `attributes` | , | Optional. |

**Response fields:**

| Field | Type | Notes |
| --- | --- | --- |
| `request_summary` | object | Normalized view of the event. |
| `ingestion.accepted` | boolean | Whether the event was accepted. |
| `ingestion.required_scopes` | string\[\] | Scopes required. |
| `ingestion.plaintext_transport` | string | Always a local-only marker. |
| `ingestion.send_only` | string\[\] | Fields the event is expected to carry. |
| `ingestion.correlate_by` | string\[\] | Correlation keys the platform will use to link this event to related records. |
| `platform_domains`, `warnings` | , | As above. |

## Enumerations

The contract uses five public enumeration types:

| Enum | Values |
| --- | --- |
| `ProtectionOperation` | `protect`, `access`, `rewrap` |
| `KeyAccessOperation` | `wrap`, `unwrap`, `rewrap` |
| `ArtifactProfile` | `tdf`, `envelope`, `detached_signature` |
| `ArtifactKind` | `data_object`, `tdf_manifest` |
| `EvidenceEventType` | `protect`, `access`, `rewrap`, `deny` |

All enum values are lowercase snake_case. Unknown values are rejected at request validation; the OpenAPI document is authoritative.

## Relationship to other pages

- [SDKs](https://lattix.io/docs/sdks/), idiomatic clients for all three supported languages.
- [Authentication](https://lattix.io/docs/api/authentication/), how callers authenticate before hitting these routes.
- [Trusted Data Format](https://lattix.io/docs/concepts/trusted-data-format/), the `tdf` artifact profile is the TDF envelope.
- [Immutable Ledger](https://lattix.io/docs/concepts/immutable-ledger/), where evidence events land.

[Authentication How callers authenticate to the Lattix Platform API using OAuth 2.0 client credentials, OIDC issuer metadata, sender-constrained bearer tokens, tenant binding, scopes, and mTLS proof-of-possession.](https://lattix.io/docs/api/authentication/) [API Explorer Interactive navigation of the Lattix SDK control-plane API: operations, parameters, request and response shapes, driven by the published OpenAPI spec.](https://lattix.io/docs/api/explorer/)