# Collections and shares API

> Group captured requests into collections, create and revoke public share links for requests and collections, list active links and read a shared link.

Source: https://www.apitraffic.io/docs/api-reference/collections-and-shares

A collection is a named set of captured requests in a bucket, such as "Checkout issues to review", that your team keeps for later. A share link is a public, unguessable URL to one request or one collection, for someone outside your account. See [Collections](https://www.apitraffic.io/docs/collections) and [Share requests and collections](https://www.apitraffic.io/docs/sharing) for doing this in the app.

**Plan:** collections need a plan that includes **Collections**; share links need **Share links** (sharing a collection needs both). The number of collections an account can keep depends on the plan. Reading, deleting and revoking keep working if the plan changes, but existing share links stop opening when the plan no longer includes share links. **Permissions:** any member, or a `user` or `administrator` API token.

> **Warning:** Anyone with a share link can see the request in full, including its bodies after redaction. Set an expiry when you create one, and revoke links you no longer need.

## The collection object

- **sid (string, required)**:
  The collection's identifier (`col_` followed by 27 letters and digits).

- **bucketSid (string, required)**:
  The bucket.

- **name (string, required)**:
  The collection's name.

- **details (string, required)**:
  A description. Empty when there is none.

- **requestCount (number)**:
  How many requests it holds.

- **requests (object[])**:
  From [Get collection](#get-collection): the requests in it, each with `sid` (the entry, `cr_…`), `collectionSid`, `requestSid`, `name` (a label for the entry) and `createdAt`.

- **createdAt (string, required)**:
  When the collection was created (ISO 8601).

- **updatedAt (string | null)**:
  When it was last changed.

## List collections

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/collections`

Returns the collections in a bucket, with how many requests each holds.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

### Response

- **records (object[], required)**:
  The collections, as [collection objects](#the-collection-object) with `requestCount`.

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/collections \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/collections`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const { records } = await response.json();
```

```json 200
{
  "records": [
    {
      "sid": "col_2nP6qR8sT1uV3wX5yZ7aB9cD2eF",
      "bucketSid": "k3m9p2x",
      "name": "Checkout issues to review",
      "details": "Failed and slow checkouts from this week.",
      "createdAt": "2026-10-13T09:00:00.000Z",
      "updatedAt": null,
      "requestCount": 6
    }
  ]
}
```

## Get collection

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/collections/{collectionSid}`

Returns a collection with the list of requests in it. Fetch each one with [Get request](https://www.apitraffic.io/docs/api-reference/requests#get-request).

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **collectionSid (path, string, required)**:
  The collection's identifier.

### Response

A [collection object](#the-collection-object) with `requests` and `requestCount`.

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/collections/col_2nP6qR8sT1uV3wX5yZ7aB9cD2eF \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const collectionSid = 'col_2nP6qR8sT1uV3wX5yZ7aB9cD2eF';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/collections/${collectionSid}`,
  { headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` } },
);
const collection = await response.json();
```

```json 200
{
  "sid": "col_2nP6qR8sT1uV3wX5yZ7aB9cD2eF",
  "bucketSid": "k3m9p2x",
  "name": "Checkout issues to review",
  "details": "Failed and slow checkouts from this week.",
  "createdAt": "2026-10-13T09:00:00.000Z",
  "updatedAt": null,
  "requests": [
    {
      "sid": "cr_2pR7sT9uV1wX3yZ5aB8cD2eF4gH",
      "collectionSid": "col_2nP6qR8sT1uV3wX5yZ7aB9cD2eF",
      "requestSid": "req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY",
      "name": "Capture timed out",
      "createdAt": "2026-10-19T14:30:00.000Z"
    }
  ],
  "requestCount": 1
}
```

## Create collection

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/collections`

Creates an empty collection.

**Plan:** needs **Collections**; past the plan's collection limit, the API answers `409` with code `2213`.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

### Body parameters

- **name (body, string, required)**:
  The name, up to 255 characters.

- **details (body, string | null)**:
  A description.

### Response

The new [collection object](#the-collection-object), with `requestCount: 0`.

```bash cURL
curl -X POST https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/collections \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Payments incident: failed captures", "details": "502s from POST /v1/payments/{payment_id}/capture, 14:00 to 14:40 UTC." }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/collections`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Payments incident: failed captures',
    details: '502s from POST /v1/payments/{payment_id}/capture, 14:00 to 14:40 UTC.',
  }),
});
const collection = await response.json();
```

```json 200
{
  "sid": "col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ",
  "bucketSid": "k3m9p2x",
  "name": "Payments incident: failed captures",
  "details": "502s from POST /v1/payments/{payment_id}/capture, 14:00 to 14:40 UTC.",
  "createdAt": "2026-10-20T12:30:00.000Z",
  "updatedAt": null,
  "requestCount": 0
}
```

## Update collection

`PUT https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/collections/{collectionSid}`

Renames a collection or changes its description. Send only the fields you want to change.

**Plan:** needs **Collections**.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **collectionSid (path, string, required)**:
  The collection's identifier.

### Body parameters

- **name (body, string)**:
  The new name, up to 255 characters.

- **details (body, string | null)**:
  The new description.

### Response

The updated [collection object](#the-collection-object).

```bash cURL
curl -X PUT https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/collections/col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "INC-1019: failed captures" }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const collectionSid = 'col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/collections/${collectionSid}`,
  {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name: 'INC-1019: failed captures' }),
  },
);
const collection = await response.json();
```

```json 200
{
  "sid": "col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ",
  "bucketSid": "k3m9p2x",
  "name": "INC-1019: failed captures",
  "details": "502s from POST /v1/payments/{payment_id}/capture, 14:00 to 14:40 UTC.",
  "createdAt": "2026-10-20T12:30:00.000Z",
  "updatedAt": "2026-10-20T12:35:00.000Z"
}
```

## Delete collection

`DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/collections/{collectionSid}`

Deletes a collection. The requests in it are not deleted.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **collectionSid (path, string, required)**:
  The collection's identifier.

### Response

- **sid (string, required)**:
  The deleted collection's identifier.

- **deleted (boolean, required)**:
  `true`.

```bash cURL
curl -X DELETE https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/collections/col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const collectionSid = 'col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ';
await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/collections/${collectionSid}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
```

```json 200
{
  "sid": "col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ",
  "deleted": true
}
```

## Add request to collection

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/collections/{collectionSid}/requests`

Adds a captured request to a collection, with an optional label.

**Plan:** needs **Collections**.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **collectionSid (path, string, required)**:
  The collection's identifier.

### Body parameters

- **requestSid (body, string, required)**:
  The request to add (`req_…`).

- **name (body, string | null)**:
  A label for the entry, up to 255 characters.

### Response

- **sid (string, required)**:
  The entry's identifier (`cr_…`). Use it to rename or remove the entry.

- **collectionSid (string, required)**:
  The collection.

- **requestSid (string, required)**:
  The request.

- **name (string | null)**:
  The label.

- **createdAt (string, required)**:
  When it was added.

```bash cURL
curl -X POST https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/collections/col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ/requests \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "requestSid": "req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY", "name": "Capture timed out" }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const collectionSid = 'col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/collections/${collectionSid}/requests`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ requestSid: 'req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY', name: 'Capture timed out' }),
  },
);
const entry = await response.json();
```

```json 200
{
  "sid": "cr_2pR7sT9uV1wX3yZ5aB8cD2eF4gH",
  "collectionSid": "col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ",
  "requestSid": "req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY",
  "name": "Capture timed out",
  "createdAt": "2026-10-20T12:40:00.000Z"
}
```

## Rename collection request

`PUT https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/collections/{collectionSid}/requests/{collectionRequestSid}`

Changes the label of a request in a collection.

**Plan:** needs **Collections**.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **collectionSid (path, string, required)**:
  The collection's identifier.

- **collectionRequestSid (path, string, required)**:
  The entry's identifier (`cr_…`), not the request's.

### Body parameters

- **name (body, string | null, required)**:
  The new label, up to 255 characters. Send `null` or `""` to clear it.

### Response

The updated entry, as in [Add request to collection](#add-request-to-collection).

```bash cURL
curl -X PUT https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/collections/col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ/requests/cr_2pR7sT9uV1wX3yZ5aB8cD2eF4gH \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "First 502, 14:02 UTC" }'
```

```js Node.js
const base = 'https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x';
const response = await fetch(
  `${base}/collections/col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ/requests/cr_2pR7sT9uV1wX3yZ5aB8cD2eF4gH`,
  {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name: 'First 502, 14:02 UTC' }),
  },
);
const entry = await response.json();
```

```json 200
{
  "sid": "cr_2pR7sT9uV1wX3yZ5aB8cD2eF4gH",
  "collectionSid": "col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ",
  "requestSid": "req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY",
  "name": "First 502, 14:02 UTC",
  "createdAt": "2026-10-20T12:40:00.000Z"
}
```

## Remove request from collection

`DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/collections/{collectionSid}/requests/{collectionRequestSid}`

Removes a request from a collection. The request itself is not deleted.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **collectionSid (path, string, required)**:
  The collection's identifier.

- **collectionRequestSid (path, string, required)**:
  The entry's identifier (`cr_…`).

### Response

- **sid (string, required)**:
  The removed entry's identifier.

- **deleted (boolean, required)**:
  `true`.

```bash cURL
curl -X DELETE https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/collections/col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ/requests/cr_2pR7sT9uV1wX3yZ5aB8cD2eF4gH \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const base = 'https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x';
await fetch(`${base}/collections/col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ/requests/cr_2pR7sT9uV1wX3yZ5aB8cD2eF4gH`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
```

```json 200
{
  "sid": "cr_2pR7sT9uV1wX3yZ5aB8cD2eF4gH",
  "deleted": true
}
```

## The share link object

- **sid (string, required)**:
  The link's identifier: `shr_…` for a request link, `cs_…` for a collection link.

- **accountSid (string, required)**:
  The account.

- **bucketSid (string, required)**:
  The bucket.

- **requestSid (string)**:
  For a request link, the request.

- **collectionSid (string)**:
  For a collection link, the collection.

- **name (string | null)**:
  A label for the link.

- **shareToken (string, required)**:
  The secret in the link. The page to send is `https://app.apitraffic.io/shared/{shareToken}` for a request and `https://app.apitraffic.io/shared/collections/{shareToken}` for a collection.

- **createdBy (string | null)**:
  The user who created it; `null` when it was created with an API token.

- **createdAt (string, required)**:
  When it was created (ISO 8601).

- **expiresAt (string | null)**:
  When it stops working. `null` for never.

- **isRevoked (boolean, required)**:
  Whether it was revoked, and `revokedAt` when.

## Share a request

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/requests/{requestSid}/share`

Creates a public link to one request. A request has at most one active link: if it already has one, that link is returned unchanged.

**Plan:** needs **Share links**.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **requestSid (path, string, required)**:
  The request to share.

### Body parameters

- **expiresIn (body, string, default never)**:
  `24h`, `7d`, `30d` or `never`.

- **name (body, string | null)**:
  A label for the link, up to 255 characters.

### Response

A [share link object](#the-share-link-object).

```bash cURL
curl -X POST https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/requests/req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY/share \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "expiresIn": "7d", "name": "For the payments provider" }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const requestSid = 'req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/requests/${requestSid}/share`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ expiresIn: '7d', name: 'For the payments provider' }),
  },
);
const share = await response.json();
const link = `https://app.apitraffic.io/shared/${share.shareToken}`;
```

```json 200
{
  "sid": "shr_2sU1vW3xY5zA7bC9dE2fG4hJ6kL",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "bucketSid": "k3m9p2x",
  "requestSid": "req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY",
  "name": "For the payments provider",
  "shareToken": "Qm9vZ2llV29vZ2llQm9vZ2llV29vZ2llQm9vZ2llV29vZ2ll",
  "createdBy": "usr_2jL4kM6nB8vC1xZ3aS5dF7gH9qW",
  "createdAt": "2026-10-20T12:45:00.000Z",
  "expiresAt": "2026-10-27T12:45:00.000Z",
  "isRevoked": false,
  "revokedAt": null
}
```

## Get request share

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/requests/{requestSid}/share`

Returns the active link for a request. Answers `404` when the request has none.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **requestSid (path, string, required)**:
  The request.

### Response

A [share link object](#the-share-link-object).

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/requests/req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY/share \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const requestSid = 'req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/requests/${requestSid}/share`,
  { headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` } },
);
const share = response.status === 404 ? null : await response.json();
```

```json 200
{
  "sid": "shr_2sU1vW3xY5zA7bC9dE2fG4hJ6kL",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "bucketSid": "k3m9p2x",
  "requestSid": "req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY",
  "name": "For the payments provider",
  "shareToken": "Qm9vZ2llV29vZ2llQm9vZ2llV29vZ2llQm9vZ2llV29vZ2ll",
  "createdBy": "usr_2jL4kM6nB8vC1xZ3aS5dF7gH9qW",
  "createdAt": "2026-10-20T12:45:00.000Z",
  "expiresAt": "2026-10-27T12:45:00.000Z",
  "isRevoked": false,
  "revokedAt": null
}
```

## Revoke request share

`DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/requests/{requestSid}/share`

Revokes a request's active link. It stops opening immediately.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **requestSid (path, string, required)**:
  The request.

### Response

- **sid (string, required)**:
  The revoked link's identifier.

- **deleted (boolean, required)**:
  `true`.

```bash cURL
curl -X DELETE https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/requests/req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY/share \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const requestSid = 'req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY';
await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/requests/${requestSid}/share`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
```

```json 200
{
  "sid": "shr_2sU1vW3xY5zA7bC9dE2fG4hJ6kL",
  "deleted": true
}
```

## Share a collection

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/collections/{collectionSid}/share`

Creates a public link to a collection. Viewers see every request in it, in full. A collection has at most one active link: if it already has one, that link is returned unchanged.

**Plan:** needs **Collections** and **Share links**.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **collectionSid (path, string, required)**:
  The collection.

### Body parameters

- **expiresIn (body, string, default never)**:
  `24h`, `7d`, `30d` or `never`.

- **name (body, string | null)**:
  A label for the link, up to 255 characters.

### Response

A [share link object](#the-share-link-object) with `collectionSid`.

```bash cURL
curl -X POST https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/collections/col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ/share \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "expiresIn": "30d" }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const collectionSid = 'col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/collections/${collectionSid}/share`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ expiresIn: '30d' }),
  },
);
const share = await response.json();
const link = `https://app.apitraffic.io/shared/collections/${share.shareToken}`;
```

```json 200
{
  "sid": "cs_2tV2wX4yZ6aB8cD1eF3gH5jK7lM",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "bucketSid": "k3m9p2x",
  "collectionSid": "col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ",
  "name": null,
  "shareToken": "V29vZ2llQm9vZ2llV29vZ2llQm9vZ2llV29vZ2llQm9vZ2ll",
  "createdBy": "usr_2jL4kM6nB8vC1xZ3aS5dF7gH9qW",
  "createdAt": "2026-10-20T12:50:00.000Z",
  "expiresAt": "2026-11-19T12:50:00.000Z",
  "isRevoked": false,
  "revokedAt": null
}
```

## Get collection share

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/collections/{collectionSid}/share`

Returns the active link for a collection. Answers `404` when it has none.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **collectionSid (path, string, required)**:
  The collection.

### Response

A [share link object](#the-share-link-object).

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/collections/col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ/share \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const collectionSid = 'col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/collections/${collectionSid}/share`,
  { headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` } },
);
const share = response.status === 404 ? null : await response.json();
```

```json 200
{
  "sid": "cs_2tV2wX4yZ6aB8cD1eF3gH5jK7lM",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "bucketSid": "k3m9p2x",
  "collectionSid": "col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ",
  "name": null,
  "shareToken": "V29vZ2llQm9vZ2llV29vZ2llQm9vZ2llV29vZ2llQm9vZ2ll",
  "createdBy": "usr_2jL4kM6nB8vC1xZ3aS5dF7gH9qW",
  "createdAt": "2026-10-20T12:50:00.000Z",
  "expiresAt": "2026-11-19T12:50:00.000Z",
  "isRevoked": false,
  "revokedAt": null
}
```

## Revoke collection share

`DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/collections/{collectionSid}/share`

Revokes a collection's active link.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **collectionSid (path, string, required)**:
  The collection.

### Response

- **sid (string, required)**:
  The revoked link's identifier.

- **deleted (boolean, required)**:
  `true`.

```bash cURL
curl -X DELETE https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/collections/col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ/share \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const collectionSid = 'col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ';
await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/collections/${collectionSid}/share`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
```

```json 200
{
  "sid": "cs_2tV2wX4yZ6aB8cD1eF3gH5jK7lM",
  "deleted": true
}
```

## List share links

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/shares`

Returns the account's active request links. Use it to review what is shared and revoke what is not needed.

Three related operations take the same parameters and return the same shape:

| Operation | Returns |
| --- | --- |
| `GET /v1/accounts/{accountSid}/shares` | Active request links in the account |
| `GET /v1/accounts/{accountSid}/buckets/{bucketSid}/shares` | Active request links in one bucket |
| `GET /v1/accounts/{accountSid}/collection-shares` | Active collection links in the account |
| `GET /v1/accounts/{accountSid}/buckets/{bucketSid}/collection-shares` | Active collection links in one bucket |

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

### Response

- **records (object[], required)**:
  The links, as [share link objects](#the-share-link-object).

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/shares \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/shares`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const { records } = await response.json();
const neverExpire = records.filter((share) => share.expiresAt === null);
```

```json 200
{
  "records": [
    {
      "sid": "shr_2sU1vW3xY5zA7bC9dE2fG4hJ6kL",
      "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
      "bucketSid": "k3m9p2x",
      "requestSid": "req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY",
      "name": "For the payments provider",
      "shareToken": "Qm9vZ2llV29vZ2llQm9vZ2llV29vZ2llQm9vZ2llV29vZ2ll",
      "createdBy": "usr_2jL4kM6nB8vC1xZ3aS5dF7gH9qW",
      "createdAt": "2026-10-20T12:45:00.000Z",
      "expiresAt": "2026-10-27T12:45:00.000Z",
      "isRevoked": false,
      "revokedAt": null
    }
  ]
}
```

## Revoke share link

`DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/shares/{shareSid}`

Revokes a request link by its sid. For a collection link, use `DELETE /v1/accounts/{accountSid}/collection-shares/{shareSid}` with the `cs_…` sid; it takes the same parameters and returns the same response.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **shareSid (path, string, required)**:
  The link's identifier.

### Response

- **sid (string, required)**:
  The revoked link's identifier.

- **deleted (boolean, required)**:
  `true`.

```bash cURL
curl -X DELETE https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/shares/shr_2sU1vW3xY5zA7bC9dE2fG4hJ6kL \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/shares/shr_2sU1vW3xY5zA7bC9dE2fG4hJ6kL`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
```

```json 200
{
  "sid": "shr_2sU1vW3xY5zA7bC9dE2fG4hJ6kL",
  "deleted": true
}
```

## Read a shared request

`GET https://api.apitraffic.io/v1/shared/{shareToken}`

Returns the request behind a share link. This is what the share page calls. It needs no token: the share token is the authorization.

The link stops working when it is revoked, when it expires, when the account's plan no longer includes share links, or when the account closes. Each of these answers `404`.

### Path parameters

- **shareToken (path, string, required)**:
  The token from the link.

### Response

The [request object](https://www.apitraffic.io/docs/api-reference/requests#the-request-object), with bodies.

```bash cURL
curl https://api.apitraffic.io/v1/shared/Qm9vZ2llV29vZ2llQm9vZ2llV29vZ2llQm9vZ2llV29vZ2ll
```

```js Node.js
const shareToken = 'Qm9vZ2llV29vZ2llQm9vZ2llV29vZ2llQm9vZ2llV29vZ2ll';
const response = await fetch(`https://api.apitraffic.io/v1/shared/${shareToken}`);
const sharedRequest = await response.json();
```

```json 200
{
  "sid": "req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY",
  "bucketSid": "k3m9p2x",
  "direction": "in",
  "createdAt": "2026-10-19T14:21:07.412Z",
  "endpoint": "/v1/payments/{payment_id}/capture",
  "request": { "method": "POST", "path": "/v1/payments/pi_3f9a1c7e2b4d6a/capture", "body": { "amount": 8450, "currency": "usd" } },
  "response": { "statusCode": 502, "body": { "error": "upstream_timeout" } }
}
```

The example shortens the request object.

## Read a shared collection

`GET https://api.apitraffic.io/v1/shared/collections/{shareToken}`

Returns the collection behind a share link, with every request in it. No token is needed. The same conditions as [Read a shared request](#read-a-shared-request) end the link.

### Path parameters

- **shareToken (path, string, required)**:
  The token from the link.

### Response

A [collection object](#the-collection-object) whose `requests` entries each carry `requestData`: the full [request object](https://www.apitraffic.io/docs/api-reference/requests#the-request-object), or nothing when the request has been deleted or aged out. When some requests could not be read right now, the response also has `degraded: true`, `failed: ["requests"]` and `unavailableRequestSids`.

```bash cURL
curl https://api.apitraffic.io/v1/shared/collections/V29vZ2llQm9vZ2llV29vZ2llQm9vZ2llV29vZ2llQm9vZ2ll
```

```js Node.js
const shareToken = 'V29vZ2llQm9vZ2llV29vZ2llQm9vZ2llV29vZ2llQm9vZ2ll';
const response = await fetch(`https://api.apitraffic.io/v1/shared/collections/${shareToken}`);
const collection = await response.json();
```

```json 200
{
  "sid": "col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ",
  "bucketSid": "k3m9p2x",
  "name": "INC-1019: failed captures",
  "details": "502s from POST /v1/payments/{payment_id}/capture, 14:00 to 14:40 UTC.",
  "createdAt": "2026-10-20T12:30:00.000Z",
  "updatedAt": "2026-10-20T12:35:00.000Z",
  "requests": [
    {
      "sid": "cr_2pR7sT9uV1wX3yZ5aB8cD2eF4gH",
      "collectionSid": "col_2qS8tU1vW3xY5zA7bC9dE2fG4hJ",
      "requestSid": "req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY",
      "name": "First 502, 14:02 UTC",
      "createdAt": "2026-10-20T12:40:00.000Z",
      "requestData": { "sid": "req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY", "endpoint": "/v1/payments/{payment_id}/capture" }
    }
  ],
  "requestCount": 1
}
```

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| `400` | `1000` | A field is missing or invalid, for example a `name` over 255 characters or an unknown `expiresIn`. |
| `400` | `3001` | The collection, entry or link could not be created. |
| `403` | `2221` | The plan does not include collections or share links. |
| `403` | `2509` | Changing or sharing the read-only sample bucket. |
| `404` | `4000` | The collection, entry or link does not exist, or a shared link is revoked, expired or no longer available. |
| `409` | `2213` | The plan's collection limit is reached. |
| `500` | `2028` | A link was found but could not be revoked. Retry. |

## Related

- [Share requests and collections](https://www.apitraffic.io/docs/sharing):
    Sharing in the app, and what viewers see.

- [Collections](https://www.apitraffic.io/docs/collections):
    Organize requests for your team.