--- title: "List a project's links" method: GET path: "/v1/projects/{project}/links" tags: ["Smart Links"] --- # List a project's links `GET /v1/projects/{project}/links` ## Request - Base URL: `https://api.subscriby.net` - URL: `https://api.subscriby.net/v1/projects/{project}/links` - Auth: HTTP bearer ```bash curl "https://api.subscriby.net/v1/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/links?archived=false&per_page=25&page=1" \ -H "Authorization: Bearer sbt_..." ``` Pages the project's links, newest first, live and archived alike unless `archived` says otherwise; `search` finds links whose name or slug contains the text. Every row carries the three addresses in `urls`. > `archived=false` keeps expired links too: they are still the creator's and still carry their figures. Read `state` on each row, which is `live`, `expired` or `archived`. ## Path parameters - `project` string, uuid, required ## Query parameters - `archived` 'true' | 'false' | '1' | '0' - `search` string - `page` integer - `per_page` integer - `sort_by` string - `sort_direction` 'asc' | 'desc' - `limit` integer ## Response `200` The page of links, newest first, each with its three addresses. - object - `data` SmartLinkResource[], required: The items on this page. - `id` string, required: The link's id. - `project_id` string, required: The project the link belongs to; slugs are unique within a project, not across projects. - `name` string, required: A creator-facing label, never shown to visitors. - `slug` string, required: The address segment after `/go/`: 2 to 32 lowercase letters, digits and hyphens. Renaming it changes the web address; the code and the bot link stay. - `code` string, required: The stable seven-character code the bot link and the attribution cookie carry. Never changes, so a printed QR and a shared bot link keep working after a rename. - `destination` object, required: Where the link sends people. - `type` string, required: `portal` (the portal home), `plan` (the checkout of one plan) or `bot` (the project's bot, the portal home when no bot is connected). - `plan_id` string, nullable, required: The plan a `plan` destination opens; null otherwise. - `plan_name` string, nullable: That plan's name, present when the relation is loaded. - `urls` object: The addresses to share, each crediting this link. - `web` string, required: The `/go/` address on the portal host. Share it anywhere; a visitor is counted once per hour and remembered for the attribution window. - `bot` string, nullable, required: The project bot's deep link carrying `via_`; null when the project runs no bot that hands out start links. - `embed` string, required: The plan-cards page to frame on the creator's own website, with the code in `via`; every card opens the portal in the top window through this link. - `state` 'expired' | 'live' | 'archived', required: `live` (counts and credits), `expired` (past `expires_at`: the address still lands on the portal home, nothing is counted) or `archived` (put out of use by the creator; the figures stay). - `expires_at` string, nullable, required: When the link stops counting, ISO 8601; null for never. - `archived_at` string, nullable, required: When the creator archived it, ISO 8601; null while in use. - `clicks` object, required: Lifetime clicks on the web address, one per visitor address per hour. - `total` integer, required: The count. - `last_at` string, nullable, required: When the address was last followed, ISO 8601; null when never. - `created_at` string, nullable, required: When the link was created, ISO 8601. - `updated_at` string, nullable, required: When it last changed, ISO 8601. - `links` object, required: Links to the first, last, previous and next pages. - `first` string, nullable, required: The first page's URL. - `last` string, nullable, required: The last page's URL. - `prev` string, nullable, required: The previous page's URL; null on the first page. - `next` string, nullable, required: The next page's URL; null on the last page. - `meta` object, required: The paging counters for this page. - `current_page` integer, required: The page returned, 1-indexed. - `from` integer, nullable, required: The 1-indexed position of this page's first item across every page; null when the page is empty. - `last_page` integer, required: How many pages there are. - `links` object[], required: Generated paginator links. - `url` string, nullable, required: The page's URL; null for the ellipsis and the disabled arrows. - `label` string, required: The link's label: a page number, the previous or next arrow, or an ellipsis. - `active` boolean, required: Whether this link is the current page. - `path` string, nullable, required: Base path for paginator generated URLs. - `per_page` integer, required: Number of items shown per page. - `to` integer, nullable, required: Number of the last item in the slice. - `total` integer, required: Total number of items being paginated. ## Other responses - `401`: `AUTHENTICATION_REQUIRED`: the request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an `sbt_test_` token on production). - `403`: `TOKEN_MISSING_ABILITY`: the token is valid but does not carry the ability this endpoint requires; `error.context.required_ability` names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers `FORBIDDEN`, `TEAM_TIER_REQUIRED` or `CONNECTOR_TIER_REQUIRED` with the same status, and says so in its own description. - `404`: `RESOURCE_NOT_FOUND`: an id in the path names nothing the token can see. `TENANT_MISMATCH`: the project sits outside the token's `scope:project:` allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred. - `422`: `VALIDATION_FAILED`: the payload broke a rule, and `error.fields` maps each offending key to its messages. A refusal from the domain, such as a plan that cannot go on sale or a member who cannot be removed, uses the same code with `error.message` saying why and no `fields`. - `429`: `RATE_LIMITED`: the token has spent its 300 requests a minute or 10,000 an hour; `Retry-After` says when the next one is accepted. --- [API](https://skmtc.dev/memberpass/apis/subscriby-rest-api.md) · [All operations](https://skmtc.dev/memberpass/apis/subscriby-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/memberpass/apis/subscriby-rest-api/revisions/59c4df91d764?raw)