Links for every item

Manage with the API

Create and change resource types, templates and the metadata API in code.

Everything in the dashboard's Resources screen is also available with a secret key, so you can script the setup, keep it in version control, and repeat it for test and live. This is the same API the dashboard uses.

What you need#

A secret key (sk_test_… or sk_live_…) with the scope links:write (and links:read to read). The key belongs to one environment: run the setup once per environment, test first.
Base URL https://api.becklinks.com/v1. Errors are application/problem+json with a stable code; see the error reference.
POST calls accept an Idempotency-Key header (a UUID): a retry with the same key returns the first answer instead of creating a second object.

1. Create a resource type#

Bash

curl -X POST https://api.becklinks.com/v1/resource-types \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"key":"challenge","name":"Challenge"}'

The answer has an id; the next calls use it. A key cannot be reused, even after the type is archived.

2. Create a URL template#

Bash

curl -X POST https://api.becklinks.com/v1/url-templates \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type_id": "TYPE_ID",
    "path_pattern": "/c/{id}",
    "id_format": {"kind": "preset", "preset": "numeric"},
    "deep_link_path": "/challenge/{id}",
    "redirects": {"web": "https://www.example.com/open/c/{id}{query}"},
    "allow_param_passthrough": true
  }'

Overlapping patterns are refused with 409; invalid ids, destinations and placeholders with 422 validation_failed and a JSON Pointer per field. Change a template with PATCH /v1/url-templates/{template} (destinations, pass-through, status active, disabled or archived); the pattern itself is fixed. See URL templates.

3. Configure the metadata API#

Bash

curl -X PUT https://api.becklinks.com/v1/resource-types/TYPE_ID/metadata-api \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "url_template": "https://api.example.com/public/share/challenge/{id}",
    "auth": {"type": "bearer", "secret": "YOUR_ENDPOINT_SECRET"},
    "timeout_ms": 1500,
    "ttl_seconds": 900,
    "field_mapping": {
      "title": "$.title", "description": "$.description", "image_url": "$.image_url",
      "canonical_url": "$.canonical_url", "deep_link_path": "$.app_path", "resource_status": "$.status"
    },
    "status_values": {"published": ["active"], "unpublished": ["draft"], "deleted": ["deleted"]},
    "allowed_image_hosts": ["cdn.example.com"]
  }'

The credential is write-only: the answer shows only whether a secret is set and a short hint. Leave auth out of a later update to keep the stored secret. The auth object is {"type":"none"}, {"type":"bearer","secret":"…"} or {"type":"api_key_header","header_name":"X-Api-Key","secret":"…"}. The URL must be https, on a public host, with {id} only in the path or query. See Metadata API.

4. Test it before any phone is involved#

Bash

# Call your endpoint with a real id and show what Beck Links would use
curl -X POST https://api.becklinks.com/v1/resource-types/TYPE_ID/metadata-api/test \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"id":"4521"}'

# Which template does a pasted URL match, and what would it render?
curl -X POST https://api.becklinks.com/v1/url-templates/test \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"path":"/c/4521?ref=A"}'

# The card a chat app would get
curl -X POST https://api.becklinks.com/v1/resources/preview \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"path":"/c/4521"}'

Everything the API offers here#

Action	Call
List, create resource types	`GET`, `POST /v1/resource-types`
Read, rename, archive a type	`GET`, `PATCH /v1/resource-types/{type}`
List, create templates	`GET`, `POST /v1/url-templates`
Read, change, disable, archive a template	`GET`, `PATCH /v1/url-templates/{template}`
Read, set, disable the metadata API	`GET`, `PUT /v1/resource-types/{type}/metadata-api`
Test the metadata API, a URL, a preview	`POST …/metadata-api/test`, `POST /v1/url-templates/test`, `POST /v1/resources/preview`
Refresh remembered items	`POST /v1/resources/invalidate`
Clicks and API health per type	`GET /v1/resources/stats?range=7d`

The full request and response fields are in the Resources reference.

Verify it works#

Run the setup against sk_test_…, then curl -A 'facebookexternalhit/1.1' https://acme-test.becklinks.com/c/4521: the card shows your item. Repeat with sk_live_… when the test environment is accepted.