v1.0.0
OpenAPI 3.0.3

Heldqr Management API

CRUD plus analytics for QR codes on a Heldqr account. Bearer token authentication, JSON in / JSON out.

See docs/02-api-spec.md in the source repository for the narrative reference; this document is the structural contract.

Server:https://app.heldqr.com

Production

Client Libraries
Shell Curl

codes

​
codes Operations

List codes

​
Query Parameters
  • page
    Type: integer
    min:  
    1

    1-indexed page number. Defaults to 1.

  • page_size
    Type: integer
    min:  
    1
    max:  
    200

    Items per page. Defaults to 50, max 200.

  • status
    Type: stringenum

    Filter by code status.

    values
    • active
    • suspended
    • deleted
Responses
  • application/json
  • application/json
  • application/json
  • application/json
Callbacks
Request Example for get/api/v1/codes
curl 'https://app.heldqr.com/api/v1/codes?page=1&page_size=1&status=active' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "created_at": "2026-06-26T13:16:30.142Z",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "label": null,
      "plan": "free",
      "shortcode": "string",
      "status": "active",
      "tags": [
        "string"
      ],
      "target_url": "https://example.com",
      "updated_at": "2026-06-26T13:16:30.142Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 1,
    "total": 1,
    "total_pages": 1
  }
}

A page of codes owned by the token's account.

Create a code

​
Headers
  • Idempotency-Key
    Type: string
    max length:  
    255

    Optional idempotency token. Same key + same body replays the original response; same key + different body returns 409.

Body·CreateCodeRequest
required
application/json

Code attributes.

  • target_url
    Type: string
    max length:  
    2048    Format: uri
    required
  • label
    Type: string | null
    max length:  
    200
  • shortcode
    Type: string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{2,31}$
Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Callbacks
Request Example for post/api/v1/codes
curl https://app.heldqr.com/api/v1/codes \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "label": null,
  "shortcode": "",
  "target_url": ""
}'

{
  "data": {
    "created_at": "2026-06-26T13:16:30.142Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "label": null,
    "plan": "free",
    "shortcode": "string",
    "status": "active",
    "tags": [
      "string"
    ],
    "target_url": "https://example.com",
    "updated_at": "2026-06-26T13:16:30.142Z"
  }
}

Code created.

Soft-delete a code

​
Path Parameters
  • shortcode
    Type: string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{2,31}$
    required
Responses
  • application/json
  • application/json
  • application/json
  • application/json
Callbacks
Request Example for delete/api/v1/codes/{shortcode}
curl 'https://app.heldqr.com/api/v1/codes/{shortcode}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": {
    "created_at": "2026-06-26T13:16:30.142Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "label": null,
    "plan": "free",
    "shortcode": "string",
    "status": "active",
    "tags": [
      "string"
    ],
    "target_url": "https://example.com",
    "updated_at": "2026-06-26T13:16:30.142Z"
  }
}

Code soft-deleted; row preserved for restore.

Get a code

​
Path Parameters
  • shortcode
    Type: string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{2,31}$
    required
Responses
  • application/json
  • application/json
  • application/json
  • application/json
Callbacks
Request Example for get/api/v1/codes/{shortcode}
curl 'https://app.heldqr.com/api/v1/codes/{shortcode}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": {
    "created_at": "2026-06-26T13:16:30.142Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "label": null,
    "plan": "free",
    "shortcode": "string",
    "status": "active",
    "tags": [
      "string"
    ],
    "target_url": "https://example.com",
    "updated_at": "2026-06-26T13:16:30.142Z"
  }
}

Code metadata.

Update a code

​
Path Parameters
  • shortcode
    Type: string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{2,31}$
    required
Body·UpdateCodeRequest
required
application/json

Fields to update. Omitted fields are unchanged.

  • label
    Type: string | null
    max length:  
    200
  • target_url
    Type: string
    max length:  
    2048    Format: uri
Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Callbacks
Request Example for patch/api/v1/codes/{shortcode}
curl 'https://app.heldqr.com/api/v1/codes/{shortcode}' \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "label": null,
  "target_url": ""
}'

{
  "data": {
    "created_at": "2026-06-26T13:16:30.142Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "label": null,
    "plan": "free",
    "shortcode": "string",
    "status": "active",
    "tags": [
      "string"
    ],
    "target_url": "https://example.com",
    "updated_at": "2026-06-26T13:16:30.142Z"
  }
}

Updated code metadata.

scans (Collapsed)

​
scans Operations

meta (Collapsed)

​
meta Operations

Models