# 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](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](/docs/identifiers)'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](/docs/api/getWalletEligibility): GET Read the benefits one or more wallets reach Callable today

[GET /v1/availability](/docs/api/getBenefitAvailability): GET Read the benefits one or more instruments carry Callable today

[GET /v1/registry/companies](/docs/api/listRegistryCompanies): GET Read the companies one registry holds Callable today

[GET /v1/registry/instruments](/docs/api/readRegistryInstrumentFacts): GET Read the facts of one or more listed instruments Callable today

[GET /v1/claims/{id}](/docs/api/getClaim): GET Read one claim this distributor recorded Callable today

[POST /v1/claims/{id}/link](/docs/api/reissueClaimLink): POST Reissue the redemption link of one claim this distributor recorded Callable today

[GET /v1/status](/docs/api/getApiStatus): GET Check the API status Callable today

[POST /v1/claims/challenge](/docs/api/requestClaimChallenge): POST Ask for the challenge a wallet signs to claim a benefit Callable today

[POST /v1/claims](/docs/api/recordClaim): POST Record a claim a wallet's own signature or a distributor's signed statement stands behind Callable today

[GET /v1/fulfilments](/docs/api/listPendingFulfilments): GET List the fulfilments waiting on this distributor Callable today

[POST /v1/fulfilments/{id}/confirm](/docs/api/confirmFulfilment): POST Confirm one fulfilment waiting on this distributor Callable today

[POST /v1/connect/sessions](/docs/api/createConnectSession): POST Create a Connect session Callable today

[GET /v1/connect/sessions/{id}](/docs/api/getConnectSession): GET Read a Connect session Callable today

## 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](/docs/errors#limits-heading) 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.

The sample refusal

```
{
  "message": "The wallet could not be read."
}
```

The [errors and limits page](/docs/errors#statuses-heading) carries every refusal status the document declares, each in its own words.