> ## Documentation Index > Fetch the complete documentation index at: https://shortpen.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List Links > Returns a paginated list of links for the workspace associated with the API token. Supports optional workspace override and pagination controls. Returns a paginated list of links belonging to the workspace associated with your API token. Use this endpoint to browse existing links, retrieve `id` values for editing, or synchronise link data with external systems. The `id` field in each returned item is the `url_id` you need when calling the [Edit Link](./edit-link) endpoint. ### Query parameters | Parameter | Type | Default | Description | | -------------- | ------- | --------------- | ------------------------------ | | `page` | integer | `1` | Page number (1-based). | | `limit` | integer | `100` | Links per page. Maximum `100`. | | `workspace_id` | integer | first workspace | Workspace to scope results to. | ### Response payload The response uses the standard envelope and adds pagination metadata: * `data` — array of link objects (see schema below). * `count` — number of items in the current page. * `total` — total number of links matching the query. * `page` — current page number. ### Link object fields Each item in `data` exposes the following properties: | Field | Type | Description | | -------------------------- | ----------------- | ---------------------------------------------------------------------------------------------- | | `id` | integer | Unique link identifier. | | `title` | string | Human-friendly title (if set). | | `url` | string | Destination URL. | | `link` | string | Fully qualified link (domain + slug). | | `short_url` | string | **Deprecated** — same value as `link`. Will be removed in a future version; migrate to `link`. | | `qr` | string \| null | Base64 QR code PNG if generated. | | `starred` | boolean | Whether the link is starred. | | `redirect_type` | integer | `301` or `302`. | | `domain_id` | integer | Domain hosting the link. | | `folder_id` | integer \| null | Folder assignment. | | `pixel_id` | integer \| null | Associated tracking pixel. | | `workspace_id` | integer | Owning workspace. | | `organization_id` | integer | Owning organization. | | `link_cloak` | boolean | Whether URL cloaking is active. | | `hide_referer` | boolean | Whether the referrer header is removed. | | `with_password` | boolean | Whether the link is password-protected. | | `params` | object \| null | Query parameters appended to the destination. | | `social_share_title` | string \| null | Custom OpenGraph title. | | `social_share_description` | string \| null | Custom OpenGraph description. | | `social_share_image` | string \| null | Social preview image URL. | | `created_at` | string (ISO 8601) | When the link was created. | | `updated_at` | string (ISO 8601) | When the link was last modified. | ## OpenAPI ````yaml GET /v1/links openapi: 3.1.0 info: title: ShortPen API version: 1.0.0 description: >- Create branded links, fetch organization resources, and pull analytics programmatically with the ShortPen REST API. servers: - url: https://{environment}.shortpen.com description: ShortPen API host variables: environment: default: api enum: - api - staging-api security: [] tags: - name: Core description: Utility endpoints for checking service health. - name: Authentication description: Endpoints that return identity, limits, and feature availability. - name: Links description: Create, edit, and list links and their auxiliary assets like QR codes. - name: Resources description: >- Lookup supporting entities such as domains, workspaces, folders, and pixels. - name: Analytics description: Retrieve click analytics and raw tracking events. paths: /v1/links: get: tags: - Links summary: List links description: >- Returns a paginated list of links for the workspace associated with the API token. Supports optional workspace override and pagination controls. operationId: listLinks parameters: - name: page in: query schema: type: integer minimum: 1 default: 1 description: Page number for pagination. - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 100 description: Number of links per page (max 100). - name: workspace_id in: query schema: type: integer description: >- Workspace ID to scope results. Defaults to the first workspace when omitted. responses: '200': description: Paginated list of links content: application/json: schema: $ref: '#/components/schemas/ListLinksResponse' '401': description: Missing or invalid token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: ListLinksResponse: type: object properties: success: type: boolean example: true status_code: type: integer example: 200 message: type: string example: '' data: type: array items: $ref: '#/components/schemas/LinkListItem' count: type: integer description: Number of links returned in the current page. example: 25 total: type: integer description: Total number of links matching the query. example: 142 page: type: integer description: Current page number. example: 1 required: - success - status_code - data - count - total - page ErrorResponse: type: object properties: success: type: boolean example: false status_code: type: integer example: 401 message: type: string example: There was an error while processing your request. data: description: Optional payload returned for additional context. nullable: true required: - success - status_code - message LinkListItem: type: object properties: id: type: integer description: Unique link ID. Use this as `url_id` when editing a link. example: 501 title: type: string nullable: true example: Launch landing page url: type: string format: uri description: Destination URL. example: https://example.com/launch link: type: string format: uri description: Fully qualified link combining domain and slug. example: https://go.shortpen.com/summer-2025 short_url: type: string format: uri description: >- Deprecated — use `link` instead. Will be removed in a future version. example: https://go.shortpen.com/summer-2025 deprecated: true qr: type: string nullable: true description: Base64-encoded QR code PNG if a QR was generated. starred: type: boolean example: false redirect_type: type: integer enum: - 301 - 302 example: 301 domain_id: type: integer example: 3 folder_id: type: integer nullable: true example: 42 pixel_id: type: integer nullable: true workspace_id: type: integer example: 24 organization_id: type: integer example: 3 source_id: type: integer nullable: true link_cloak: type: boolean example: false hide_referer: type: boolean example: false with_password: type: boolean example: false params: type: object nullable: true additionalProperties: type: string social_share_title: type: string nullable: true social_share_description: type: string nullable: true social_share_image: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - url - link - short_url - starred - redirect_type - domain_id - workspace_id - organization_id - link_cloak - hide_referer - with_password - created_at - updated_at securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Personal Access Token ````