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"? } }.

Looking for the endpoints inside a customer?

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 organization lease for { orgId }.
POST /worker-token	ykp_	Mint a one-hour named-worker lease for { orgId, 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.
PUT /organizations/:orgId/template-connections/:integrationId/credential	ykp_	Supply or replace the stored credential your provided agents and flows use for that integration. See Credentials for provided agents.
DELETE /organizations/:orgId/template-connections/:integrationId/credential	ykp_	Remove the credential you supplied.
GET /worker/approvals?limit=&offset=&domainId=	worker ykt_	List approvals visible to the named worker; default 50, maximum 100. domainId narrows the list to one domain. A run approval carries its runId (and a null sessionId); a turn approval carries its sessionId (and a null runId) - the id the matching decide route takes.
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.
GET /platform/oauth-return-urls	ykp_	Read the return URLs your connect links may land on.
PUT /platform/oauth-return-urls	ykp_	Replace them with { "returnUrls": [...] } - HTTPS origins plus path prefixes, up to 50.
POST /organizations/:orgId/connect-links	ykp_ + subject	Mint a single-use, ten-minute browser link that connects an OAuth integration as the acting person; returns 201 { url, expiresAt }. See Customer tenant API.
GET / PUT /organizations/:orgId/assistant-config	ykp_	The personal-assistant agent and event webhook for that customer. See Personal assistant workers.
GET /organizations/:orgId/events?since=&worker_ref=&limit=	ykp_	Replay recorded assistant events, oldest first; default 100, maximum 500.

Credentials for provided agents

The agents and flows your releases provide live in a domain of their own inside each customer, which nobody in that customer can change. When one of them runs an integration on a stored credential - rather than one supplied with each call - the customer cannot connect it, so the release reports that integration under needsAuthorization and the customer shows as degraded. You supply it instead:

curl -X PUT "https://api.yekar.ai/api/partner/v1/organizations/$ORG_ID/template-connections/yekar.http/credential" \
  -H "Authorization: Bearer $YKP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "secrets": { "API_KEY": "…" }, "properties": { "BASE_URL": "https://api.example.com" } }'

• secrets uses the integration's own setup field names, checked exactly as the connection form checks them. Sign-in tokens cannot be entered this way.
• properties is optional. Sent, it replaces the connection's settings and must include any required one; left out, the settings stay as they are.
• Sending it again replaces the credential. DELETE removes it.
• The response carries needsAuthorization re-checked against the customer's latest release, so you see the integration clear (or return) immediately. It is null when no release has been applied yet.

Refusals: 404 for a customer your platform does not serve, 409 TEMPLATE_NOT_APPLIED before any release has reached it, 409 TEMPLATE_INTEGRATION_NOT_BOUND when none of your provided agents or flows uses that integration on a stored credential, and 400 for a field name the integration does not have. Every change is recorded in the customer's audit log against your key; the credential itself never is.

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.existingOrgId is present, that customer is yours - reconcile it (details.existingFollowerOrgId is its fleet record); otherwise choose another segment.
CLIENT_SEGMENT_INVALID	The requested URL segment is invalid.	Correct the request.

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_REUSED when the key was used with a different validated request.
• 409 IDEMPOTENCY_IN_PROGRESS with Retry-After: 2 while the winner is still executing.
• 409 IDEMPOTENCY_OUTCOME_UNKNOWN when execution may have crossed the commit boundary but no safe replay could be stored. Do not retry this response blindly.
• Idempotency-Replayed: true on 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.