> ## 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.

# Delete Link

> Deletes one or more links owned by the authenticated organization. Provide `url_id` as a single integer or an array of integers. Links are soft-deleted, so they immediately disappear from listings while their historical analytics remain recoverable.

Delete one or more links by supplying their `url_id`. Deletion is scoped to the organization tied to your API token, so you can only remove links your key owns.

<Tip>
  You can find the `url_id` of any link by calling [`GET /v1/links`](./list-links) — the `id` field in each item is the value you need.
</Tip>

### How it works

Links are **soft-deleted**: they immediately disappear from [`GET /v1/links`](./list-links) and stop resolving, but their historical analytics are retained and the link can be restored from the dashboard. The same destination slug becomes available for reuse once a link is deleted.

Pass `url_id` as either:

* a single integer — `{ "url_id": 501 }`
* an array of integers for bulk deletion — `{ "url_id": [501, 502, 503] }`

Only links belonging to the authenticated organization are affected; IDs that do not match are skipped. If none of the supplied IDs match a link in your organization, the API returns a `404`.

### Request body

| Field    | Type                  | Required | Description                                                     |
| -------- | --------------------- | -------- | --------------------------------------------------------------- |
| `url_id` | integer or integer\[] | ✅        | ID of the link to delete, or an array of IDs for bulk deletion. |

### Response highlights

* `data.deleted` — the number of links that were actually removed. With a bulk request, this can be lower than the number of IDs supplied if some did not belong to your organization.

```json theme={null}
{
  "success": true,
  "status_code": 200,
  "data": { "deleted": 1 },
  "message": "Link successfully deleted"
}
```

### Error handling

| Status | Meaning                                                                    |
| ------ | -------------------------------------------------------------------------- |
| 400    | Validation error — `url_id` is missing or contains no valid IDs.           |
| 401    | Missing or invalid API token.                                              |
| 404    | None of the supplied IDs matched a link in the authenticated organization. |


## OpenAPI

````yaml DELETE /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:
    delete:
      tags:
        - Links
      summary: Delete a link
      description: >-
        Deletes one or more links owned by the authenticated organization.
        Provide `url_id` as a single integer or an array of integers. Links are
        soft-deleted, so they immediately disappear from listings while their
        historical analytics remain recoverable.
      operationId: deleteLink
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteLinkRequest'
            examples:
              single:
                summary: Delete a single link
                value:
                  url_id: 501
              bulk:
                summary: Delete several links at once
                value:
                  url_id:
                    - 501
                    - 502
                    - 503
      responses:
        '200':
          description: Link(s) deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteLinkResponse'
        '400':
          description: Validation error — no valid `url_id` was provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No matching link found for the authenticated organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    DeleteLinkRequest:
      type: object
      properties:
        url_id:
          description: >-
            ID of the link to delete, or an array of IDs for bulk deletion. Only
            links belonging to the authenticated organization are affected.
          oneOf:
            - type: integer
              example: 501
            - type: array
              items:
                type: integer
              example:
                - 501
                - 502
                - 503
      required:
        - url_id
    DeleteLinkResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status_code:
          type: integer
          example: 200
        message:
          type: string
          example: Link successfully deleted
        data:
          type: object
          properties:
            deleted:
              type: integer
              description: Number of links that were deleted.
              example: 1
          required:
            - deleted
      required:
        - success
        - status_code
        - data
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Personal Access Token

````