API reference
Every call the distributor API serves, read from the interface description Yutai publishes, one page per call. The whole description is one document: it downloads at https://api.yutai.com/openapi.json so you can import it into your own tools. The formats every value travels in are the identifiers page's.
A call marked Callable today is served: it answers at the address its page names. Every call presents a key the platform issued to the distributor, except the ones its own page marks as taking none: those answer before any key exists. A call marked Planned is not served yet: its call answers nothing. Every sample answer is simulated: no real holder's data stands behind it.
The calls
One page per call, in the document's own order: the call's method and address, what it does, and whether Yutai serves it today.
- GET /v1/eligibility
- Read the benefits one or more wallets reach
- GET /v1/availability
- Read the benefits one or more instruments carry
- GET /v1/registry/companies
- Read the companies one registry holds
- GET /v1/registry/instruments
- Read the facts of one or more listed instruments
- GET /v1/claims/{id}
- Read one claim this distributor recorded
- POST /v1/claims/{id}/link
- Reissue the redemption link of one claim this distributor recorded
- GET /v1/status
- Check the API status
- POST /v1/claims/challenge
- Ask for the challenge a wallet signs to claim a benefit
- POST /v1/claims
- Record a claim a wallet's own signature or a distributor's signed statement stands behind
- GET /v1/fulfilments
- List the fulfilments waiting on this distributor
- POST /v1/fulfilments/{id}/confirm
- Confirm one fulfilment waiting on this distributor
- POST /v1/connect/sessions
- Create a Connect session
- GET /v1/connect/sessions/{id}
- Read a Connect session
- GET /v1/connect/outcomes
- Read a person's Connect outcomes
- DELETE /v1/connect/links/{external_ref}
- Unlink a customer account
The key
Every call that takes a key presents it in the Authorization header, as a Bearer key: Authorization: Bearer ytk_your-key. A publishable key starts with ytk_pub_ and carries 64 lowercase hex characters after it. A secret key starts with ytk_ and carries 64 lowercase hex characters after it. The placeholder ytk_your-key stands for the key you hold; no real key rides these pages.
Every call that takes a key presents one scope: the scope the call's own page names. This table lists the scopes the documented calls present, not every scope a key may carry:
eligibility.read- Read the benefits one or more wallets reach.
availability.read- List a security's available benefits, and read the registry's companies and instruments.
claims.write- Record a benefit claim, read a claim, reissue its link, and list and confirm fulfilments.
connect.write- Create a Connect session and unlink a customer account.
connect.read- Read Connect sessions and their outcomes.
claims.read- Read a claim and list the fulfilments waiting on the distributor.
Limits
Once the key a call presents stands, the call is counted, per key and per scope, in one fixed window of 60 seconds that starts on the minute. A call past the scope's own count is refused without being counted: the refusal answers the one error shape the Errors section carries, and its Retry-After header names the seconds to wait until the next window opens.
The errors and limits page carries each scope's count and how long an answer stands.
Errors
Every refused call answers one object with three fields: message, the plain sentence that says what did not happen; code, the closed refusal code the call log records beside the call; and requestId, the id to quote when asking Yutai about the call. The message carries 1 to 512 characters, the code 1 to 64 characters, and the request id 1 to 64 characters. Every answer carries the same id on its X-Request-Id header.
{
"message": "No API key answers the presented key. Nothing was read.",
"code": "unknown_key",
"requestId": "req_01K4V9QG000000000000000001"
}The errors and limits page carries every refusal status the document declares, each in its own words.