REST API reference

yorkyy's REST API uses standard HTTP, returns JSON, and authenticates with a bearer token. Base URL: https://yorkyy.com.

Authentication

Every request requires an Authorization header in the form Bearer yk_live_.... Get a key from your dashboard.

Requests without a key, with an invalid key, or with a revoked key return 401 Unauthorized with a body like:

{
  "error": {
    "code": "invalid_key",
    "message": "Unknown API key."
  }
}

Errors

Errors share a consistent shape. The code field is stable across releases:

Status	Code	Meaning
400	`bad_request`	Malformed request.
401	`missing_authorization`	No `Authorization` header.
401	`invalid_key`	Key doesn't exist or doesn't match.
401	`key_revoked`	Key was revoked.
404	`form_not_found`	Form doesn't exist or isn't yours.
429	`rate_limited`	See `Retry-After` header.

Rate limits

Read endpoints: 300 requests per minute per API key. When exceeded, you'll get a 429 with a Retry-After header indicating seconds to wait. The SDK respects this automatically.

GET /api/v1/me

Returns the authenticated user. Useful for verifying a key is valid.

curl https://yorkyy.com/api/v1/me \
  -H "Authorization: Bearer yk_live_..."

Response:

{
  "id": "01h...",
  "email": "you@example.com",
  "name": "Your Name"
}

GET /api/v1/forms

Lists up to 200 of your forms, newest first.

curl https://yorkyy.com/api/v1/forms \
  -H "Authorization: Bearer yk_live_..."

Response:

{
  "data": [
    {
      "id": "01h...",
      "public_id": "mP33VvCwDqN",
      "title": "Customer feedback",
      "status": "published",
      "created_at": "2026-05-12T18:00:00.000Z",
      "updated_at": "2026-05-15T09:30:00.000Z",
      "url": "/f/mP33VvCwDqN"
    }
  ]
}

GET /api/v1/forms/{formId}/submissions

Cursor-paginated submissions for a form. Newest first.

Query parameters:

Parameter	Type	Default	Notes
`limit`	integer	25	Max 100.
`cursor`	string	—	ISO timestamp from previous response's `next_cursor`.

curl "https://yorkyy.com/api/v1/forms/01h.../submissions?limit=50" \
  -H "Authorization: Bearer yk_live_..."

Response:

{
  "data": [
    {
      "id": "01h...",
      "data": {
        "Your name": "Ada Lovelace",
        "Email address": "ada@example.com"
      },
      "created_at": "2026-05-15T18:42:00.000Z"
    }
  ],
  "pagination": {
    "next_cursor": "2026-05-15T18:30:00.000Z",
    "has_more": true
  }
}

To page through all submissions, keep passing next_cursor as the next request's cursor until has_more is false.