Challenges

List a challenge's deliveries

GET https://api.xipid.org/challenges/{id}/deliveries

One page of the challenge's deliveries, oldest first: the events posted to its callback URL, each with its last attempt as the receiver answered it, or the class of the failure that got no answer.

Scope: any live key of the brand.

Limits: 1,000 requests a minute per key and 2,000 requests a minute per source address; every answer says what is left in X-RateLimit-Remaining, and a refusal when to come back in Retry-After.

Idempotency: a read, safe to repeat.

Changes: 2026-09-26: added.

Parameters

• id in the path, required, ULID

  XipID's id for the challenge.

• limit in the query, optional, integer, 1 to 100, 20 by default

  How many items the page holds.

• starting_after in the query, optional, string

  The page after the item a page's next_cursor named.

• ending_before in the query, optional, string

  The page before the item a page's previous_cursor named; not with starting_after.

• Xip-Version a header, optional, string, one of the values below

  The version to answer in; when absent, the version the brand's org is pinned to.

  • 2026-09-26: The first version: challenges, subjects and events, and the signed outcome.

Answers

200 OK

A page of deliveries.

Its headers: X-Request-Id, Xip-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

• data array of Delivery

  • id ULID

  • challenge_id ULID

  • event string, one of the values below

    How the challenge closed.

    • challenge.verified: The person approved and every check passed.
    • challenge.check_failed: A check the policy asks for did not pass.
    • challenge.declined: The person declined.
    • challenge.expired: No decision came before the challenge expired.
    • challenge.canceled: The brand canceled the challenge, or its text could not be sent.

  • status string, one of the values below

    Where the delivery stands.

    • pending: An attempt is due or running.
    • delivered: The receiver answered 2xx.
    • failed: Its attempts are spent, or the receiver answered a status that ends them.

  • attempts integer, at least 0

  • last_attempt object, optional

    • attempted_at instant, RFC 3339

    • duration_ms integer, at least 0

    • status_code integer, optional

    • response_headers map, each value string, optional

    • response_body string, optional

    • failure string, one of the values below, optional

      Why the attempt got no answer, by its class alone.

      • timeout: The attempt ran out of its 15 seconds.
      • dns_failure: The callback URL's host did not resolve.
      • connection_refused: The receiver refused the connection.
      • connection_reset: The receiver reset the connection.
      • tls_error: TLS failed.
      • url_refused: The callback URL was refused before anything was sent: not https on port 443, or not public.

  • next_attempt_at instant, RFC 3339, optional

  • delivered_at instant, RFC 3339, optional

  • created_at instant, RFC 3339

• has_more boolean

• next_cursor string or null

• previous_cursor string or null

{
  "data": [
    {
      "id": "01JD2RB7C9E1G3J5K7M9N1P3R5",
      "challenge_id": "01JD2R5W8Y3K6M9P2S5V8X1Z4B",
      "event": "challenge.verified",
      "status": "delivered",
      "attempts": 1,
      "last_attempt": {
        "attempted_at": "2026-11-19T18:06:41.733Z",
        "duration_ms": 184,
        "status_code": 200,
        "response_headers": {
          "content-type": "application/json"
        },
        "response_body": "{\"received\":true}"
      },
      "delivered_at": "2026-11-19T18:06:41.917Z",
      "created_at": "2026-11-19T18:06:41.090Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null
}

Errors

• json_invalid, 400: The request body is not valid JSON.
• parameter_invalid, 400: The request contains invalid parameters.
• parameter_unknown, 400: The request contains a parameter this route does not take.
• version_invalid, 400: Xip-Version names no released version of this API.
• cursor_invalid, 400: The cursor is malformed or belongs to another list.
• authentication_required, 401: Authentication is required.
• authentication_failed, 401: The credential is invalid, expired or revoked.
• insufficient_scope, 403: The credential does not allow this operation.
• resource_not_found, 404: No such resource.
• content_too_large, 413: The request body is larger than this route accepts.
• media_type_unsupported, 415: This route does not accept that Content-Type.
• rate_limit_exceeded, 429: Too many requests; try again later.
• internal_error, 500: Something went wrong on our side.
• upstream_error, 502: A service XipID depends on failed.
• service_unavailable, 503: The service is temporarily unavailable.
• upstream_timeout, 504: A service XipID depends on did not answer in time.