Resources

List resource types

Resource types of this environment, newest first. Archived ones are left out unless status=archived.

Secret key scope (any of): links:read, links:write

Parameters

Responses

Example

curl -X GET "https://api.becklinks.com/v1/resource-types" \
  -H "Authorization: Bearer $SECRET_KEY"

Create a resource type

Defines something you share through URL templates, for example challenge. The key is used in payloads and cannot be changed. An environment can have 20 resource types.

Secret key scope (any of): links:write

Request body

Responses

Example

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

Get a resource type

One resource type, archived ones included.

Secret key scope (any of): links:read, links:write

Parameters

Responses

Example

curl -X GET "https://api.becklinks.com/v1/resource-types/{type}" \
  -H "Authorization: Bearer $SECRET_KEY"

Update a resource type

Renames a resource type or archives it (status: archived). Templates of an archived type stop resolving; their patterns stay reserved. The key cannot change.

Secret key scope (any of): links:write

Parameters

Request body

Responses

Example

curl -X PATCH "https://api.becklinks.com/v1/resource-types/{type}" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Get the metadata API of a resource type

The endpoint, field mapping and cache settings. The credential is never returned: auth.secret_set says whether one is stored and auth.secret_hint shows its last characters.

Secret key scope (any of): links:read, links:write

Parameters

Responses

Example

curl -X GET "https://api.becklinks.com/v1/resource-types/{type}/metadata-api" \
  -H "Authorization: Bearer $SECRET_KEY"

Set the metadata API of a resource type

Creates or replaces the configuration (one per resource type). url_template is an https URL on a public host name with {type} and {id} in the path or query. Previews of this type then show each item’s own title, description and image from your API: it is called only for link-preview bots, its answers are cached, and a failing API never slows a visitor down. Omit auth.secret to keep the stored credential.

Secret key scope (any of): links:write

Parameters

Request body

Responses

Example

curl -X PUT "https://api.becklinks.com/v1/resource-types/{type}/metadata-api" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url_template":"string","field_mapping":{}}'

Test the metadata API with a real item

Calls your API for the item id with the saved configuration and reports what came back: the HTTP status, the time it took, the metadata that was read, and why anything was left out. Nothing is cached or counted.

Secret key scope (any of): links:write

Parameters

Request body

Responses

Example

curl -X POST "https://api.becklinks.com/v1/resource-types/{type}/metadata-api/test" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"id":"string"}'

Invalidate remembered metadata

Call it when items changed or were deleted in your system. Beck Link forgets what it remembered about them (up to 1,000 ids per call), so the next link preview asks your metadata API again. Link previews that chat apps and social networks already stored are refreshed by those services, not by this call.

Secret key scope (any of): links:write

Request body

Responses

Example

curl -X POST "https://api.becklinks.com/v1/resources/invalidate" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"resource_type":"string","ids":["string"]}'

Preview a shared URL

Resolves a URL such as https://shop.becklinks.com/c/4521 to its template and item, asks your metadata API for it right now, and returns the card a link-preview bot would see together with the state of the shared cache.

Secret key scope (any of): links:read, links:write

Request body

Responses

Example

curl -X POST "https://api.becklinks.com/v1/resources/preview" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"path":"string"}'

Get the analytics of resource links

Per resource type: non-bot clicks, the most clicked items, how link previews were answered (cache hit rate) and how your metadata API behaved (calls, errors, latency) over the last 7 or 30 project-local days. Item clicks are read from the raw click log; API figures are flushed every few seconds, so the newest minutes may be missing.

Secret key scope (any of): analytics:read

Parameters

Responses

Example

curl -X GET "https://api.becklinks.com/v1/resources/stats" \
  -H "Authorization: Bearer $SECRET_KEY"

List URL templates

Templates of this environment, newest first. Filter by resource_type_id and status; archived ones are left out unless status=archived.

Secret key scope (any of): links:read, links:write

Parameters

Responses

Example

curl -X GET "https://api.becklinks.com/v1/url-templates" \
  -H "Authorization: Bearer $SECRET_KEY"

Create a URL template

Shares path_pattern (for example /c/{id}) for a resource type on the environment’s link host. id_format says what an id looks like; deep_link_path, data and redirects may contain {id} and {type}. The pattern cannot change later. A type can have 5 templates. A destination URL that looks suspicious is saved and listed in warnings; one that is listed as dangerous is refused with 422 url_blocked.

Secret key scope (any of): links:write

Request body

Responses

Example

curl -X POST "https://api.becklinks.com/v1/url-templates" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"resource_type_id":"string","path_pattern":"string","id_format":{"kind":"preset","preset":"numeric"},"deep_link_path":"string"}'

Test a URL against the templates

Shows which template and id a URL or path resolves to and what it would render. Nothing is counted or stored.

Secret key scope (any of): links:read, links:write

Request body

Responses

Example

curl -X POST "https://api.becklinks.com/v1/url-templates/test" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"path":"string"}'

Get a URL template

One template, archived ones included.

Secret key scope (any of): links:read, links:write

Parameters

Responses

Example

curl -X GET "https://api.becklinks.com/v1/url-templates/{template}" \
  -H "Authorization: Bearer $SECRET_KEY"

Update a URL template

Changes the fields sent. The pattern and the resource type stay as they are, because links already shared depend on them. status: disabled keeps the pattern and answers with a status page; archived frees the pattern. A destination URL that looks suspicious is saved and listed in warnings; one that is listed as dangerous is refused with 422 url_blocked.

Secret key scope (any of): links:write

Parameters

Request body

Responses

Example

curl -X PATCH "https://api.becklinks.com/v1/url-templates/{template}" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'