List and retrieve requests

GET /v1/requests
GET /v1/requests/{shortCode}

Both require the requests:read scope. Both return metadata only — never a submission, never a field prompt, never a title.

List

curl "https://api.credenshare.io/v1/requests?page=1&limit=25" \
  -H "Authorization: Bearer crs_sk_live_<keyId>.<authSecret>"

Newest first, ordered by creation time.

Out-of-range values are corrected rather than rejected, so a bad limit does not fail the call — it silently gives you 25 or 100. If you depend on the page size, read it back from the pagination block rather than assuming the value you sent.

200 OK:

{
  "requests": [
    {
      "short_code": "a1b2c3d4",
      "expired_at": "2026-09-30T12:00:00Z",
      "public_key": "…"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total_pages": 2,
    "total": 34
  }
}

The pagination block is always present when the list query succeeds, and requests is always an array — an account with no requests returns [], not null and not a missing key. A client that has to guess whether more exists guesses wrong.

Retrieve one

curl https://api.credenshare.io/v1/requests/a1b2c3d4 \
  -H "Authorization: Bearer crs_sk_live_<keyId>.<authSecret>"

200 OK:

{
  "short_code": "a1b2c3d4",
  "expired_at": "2026-09-30T12:00:00Z",
  "public_key": "…"
}

Reading a request does not consume an access count, does not evaluate the passcode, and does not act on expiry. Polling your own request must not be the thing that closes it.

An expired request still answers

If the request has expired, you get 200 with the short code and expired_at and public_key set to null:

{
  "short_code": "a1b2c3d4",
  "expired_at": null
}

This is the one place the shape is narrower than usual, and it is on purpose: the metadata read errors on an expired request, so rather than invent a body or report the request as missing, the endpoint returns what it can still stand behind. An owner asking about their own expired request should not be told it never existed.

Distinguishing the three cases:

Ownership

Ownership is checked before the read, and a short code on another account returns 404 rather than 403. The two are indistinguishable from outside, which is the point: the endpoint cannot be used to find out which short codes exist elsewhere.

Errors

Note that requests:read is what gates this, not shares:read. Scopes are matched exactly and there is no hierarchy between resources.