Partner API reference
All machine endpoints are under /api/partner/v1. Send a ykp_ key unless an endpoint explicitly requires a leased ykt_ token. JSON failures use { "error": { "code", "message", "details"? } }.
This page covers fleet operations - provisioning, leases, workers, entitlements - authorized by your key alone.
To drive what is inside a customer organization (agents and flows, connections, domains, triggers, sessions, knowledge, settings), see Customer tenant API. Those endpoints live under /organizations/{orgId}/… and take an extra X-Yekar-Subject header naming the provisioned person the call acts as.
Endpoints
| Method and path | Credential | Contract |
|---|---|---|
POST /organizations | ykp_ | Provision one customer; requires Idempotency-Key; returns 202. |
POST /token | ykp_ | Mint a one-hour app lease for { orgId, appId }. |
POST /worker-token | ykp_ | Mint a one-hour named-worker lease for { orgId, appId, partnerSubject }. |
GET /organizations/:orgId/workers | ykp_ | Read mappings for that customer. |
POST /organizations/:orgId/workers | ykp_ | Vouch a named worker and domain roles. |
DELETE /organizations/:orgId/workers/:mappingId | ykp_ | Revoke a mapping. |
GET /organizations/:orgId/entitlements | ykp_ | Read default, override, and resolved standing for each agent and flow. |
PATCH /organizations/:orgId/automations/:automationId/entitlement | ykp_ | Set { "enabled": boolean } as a customer override. |
DELETE /organizations/:orgId/automations/:automationId/entitlement | ykp_ | Clear the override and return to the platform default. |
GET /worker/approvals?limit=&offset= | worker ykt_ | List approvals visible to the named worker; default 50, maximum 100. |
POST /worker/approvals/runs/:runId | worker ykt_ | Decide a run approval with decision, optional comment, and optional approvalId. |
POST /worker/approvals/sessions/:sessionId | worker ykt_ | Decide a turn approval with the same decision contract. |
GET /support-sessions/:grantId | ykt_ | Read one support session by the id delivered to you. There is no collection endpoint. |
Closed provisioning refusals
Provisioning uses this closed set. Treat error.code as the stable decision field.
| Code | Meaning | Retry posture |
|---|---|---|
PARTNER_PLATFORM_SUSPENDED | The platform or partner is not accepting provisioning. | Wait for standing to be restored. |
PROVISIONING_NOT_ENABLED | This key is not entitled to create customers. | Correct the platform grant. |
TEMPLATE_SUSPENDED | The template is unavailable. | Restore the template before retrying. |
QUOTA_EXHAUSTED | The durable customer allowance is exhausted. | Raise the allowance; request-rate retries do not help. |
IDENTIFIER_TAKEN | The requested customer identifier is unavailable. | If details.existing is present, reconcile that returned customer; otherwise choose another segment. |
CLIENT_SEGMENT_INVALID | The requested URL segment is invalid. | Correct the request. |
PROVISIONING_FAILED | Provisioning could not complete. | Inspect the returned onboarding state before retrying. |
Authentication failures are deliberately neutral. Customer ids outside your platform and nonexistent ids are not distinguishable through protected reads and writes.
Accepted work and retries
202 Accepted means the durable customer record exists; it does not claim every onboarding step has already converged. Read onboardingStatus and the release detail in the response.
Provisioning additionally returns:
409 IDEMPOTENCY_KEY_REUSEDwhen the key was used with a different validated request.409 IDEMPOTENCY_IN_PROGRESSwithRetry-After: 2while the winner is still executing.409 IDEMPOTENCY_OUTCOME_UNKNOWNwhen execution may have crossed the commit boundary but no safe replay could be stored. Do not retry this response blindly.Idempotency-Replayed: trueon a successful seven-day replay.
Request-volume limits return 429 with Retry-After. Honor the header and add jitter. Quota refusals are durable business bounds, not rate limits.