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
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. The scopes a key may carry come from one closed list:
holders.resolve- Resolve the holder a wallet belongs to.
credentials.read- Read a holder's credential status.
benefits.list- List a holder's benefits.
eligibility.read- Read the benefits one or more wallets reach.
availability.read- List a security's available benefits.
claims.write- Record a benefit claim.
connect.write- Create a Connect session and unlink a customer account.
connect.read- Read Connect sessions and their outcomes.
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 one field, message: the plain sentence that says what did not happen. The sentence carries 1 to 512 characters, so a refusal never carries an id, a code or an exception's text.
{
"message": "The wallet could not be read."
}The errors and limits page carries every refusal status the document declares, each in its own words.