# Ingest Keys

## Ingest Key Model

### Fields

- **`object`** `"ingest_key"`

- **`id`** `string`

   Unique identifier, prefixed with `ik_`.

- **`source_id`** `string`

   The source this key writes into.

- **`source_name`** `string | null`

- **`url`** `string | null`

   The Tailglow-issued address to send records to, ready to use. POST your payload to it and
   append `&collection=<name>` to choose where the records land; a collection is created the first
   time data arrives for it. Lasts as long as the project does. Null until the project has a
   provisioned server, which is the only window in which no address reaches it.

- **`custom_urls`** `string[]`

   The same source reached through the team's verified custom ingest domains, one entry each,
   every one carrying the key exactly as `url` does. Empty when none are configured. Prefer these
   for browser traffic, where a first-party host survives the blockers that reject a shared
   analytics domain. An entry disappears if its domain is removed or stops resolving.

- **`key`** `string`

   The credential embedded in `url`. Publishable, in the sense that it belongs in client-side code
   the way an analytics site tag does. It permits writing records into this source and nothing
   else: it cannot read, and it carries no access to anything outside this source.

- **`status`** [`IngestKeyStatus`](/api/ingest_keys#ingest-key-status)

   Whether records sent to this URL are still accepted.

- **`created_at`** [`ISODateString`](/api/ingest_keys#iso-date-string)

- **`last_used_at`** [`ISODateString | null`](/api/ingest_keys#iso-date-string)

   When data was last received at this URL; null if it has never been used.

### Referenced Types

#### ISODateString

`ISODateString`

An ISO 8601 date-time string returned at the JSON API boundary.

#### IngestKeyStatus

`"active" | "revoked" | "disabled"`

## List Ingest Keys

### Endpoint

Retrieve every address that can send records to a source.

```http
GET /v1/projects/:project_id/sources/:source_id/ingest_keys
```

**Scope:** `ingest_keys:read`

### Path Parameters

- **`project_id`** `string` -- **Required**
  Unique identifier of the project.

- **`source_id`** `string` -- **Required**
  Unique identifier of the source.

### Query Parameters

- **`order_by`** `string`
  Field used to order the ingest keys. Optional. Defaults to `"created_at"`. Allowed values: `"created_at"`, `"status"`.

- **`status`** [`IngestKeyStatus`](/api/ingest_keys#ingest-key-status)
  Filter by whether the URL still accepts records. Optional.

- **`project_id`** `string`
  Filter to URLs whose source belongs to a project. Optional.

- **`source_id`** `string`
  Filter to URLs belonging to a single source. Optional.

- **`limit`** `number`
  Maximum number of items to return. Optional. Defaults to `25`. Minimum: `1`. Maximum: `200`.

- **`after`** `string`
  Cursor from `pagination.next_cursor` of a previous response. Returns the resources after that page. Optional.

- **`before`** `string`
  Cursor from `pagination.prev_cursor` of a previous response. Returns the resources before that page. Optional.

- **`sort`** `string`
  Sort direction for the result set. Optional. Defaults to `"desc"`. Allowed values: `"asc"`, `"desc"`.

### Response

```ts
{
  message: string;
  data: IngestKey[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}
```

### Comments

- `after` and `before` are mutually exclusive.

## Retrieve Ingest Key

### Endpoint

Retrieve a single ingest key.

```http
GET /v1/projects/:project_id/sources/:source_id/ingest_keys/:ingest_key_id
```

**Scope:** `ingest_keys:read`

### Path Parameters

- **`project_id`** `string` -- **Required**
  Unique identifier of the project.

- **`source_id`** `string` -- **Required**
  Unique identifier of the source.

- **`ingest_key_id`** `string` -- **Required**
  Unique identifier of the ingest key.

### Response

Ingest key retrieved

```ts
{
  message: string;
  data: IngestKey;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}
```

## Create Ingest Key

### Endpoint

Create an ingest key for a source. Use this to rotate: create the replacement, deploy it, then delete the old one.

```http
POST /v1/projects/:project_id/sources/:source_id/ingest_keys
```

**Scope:** `ingest_keys:write`

### Path Parameters

- **`project_id`** `string` -- **Required**
  Unique identifier of the project.

- **`source_id`** `string` -- **Required**
  Unique identifier of the source.

### Request Body

- **`source_id`** `string`
  Source the URL writes into. Ignored when the nested path supplies it. Optional.

### Response

Ingest key created.

```ts
{
  message: string;
  data: IngestKey;
  status: 201;
  error: null;
  pagination: null;
  endpoint: string;
}
```

### Comments

- The source is supplied by the path.
- The source has to belong to your team.
- The full `key` is returned on create and never again. Store it when you receive it.

## Delete Ingest Key

### Endpoint

Delete an ingest key. Records already sent to it are unaffected; the address stops being accepted.

```http
DELETE /v1/projects/:project_id/sources/:source_id/ingest_keys/:ingest_key_id
```

**Scope:** `ingest_keys:delete`

### Path Parameters

- **`project_id`** `string` -- **Required**
  Unique identifier of the project.

- **`source_id`** `string` -- **Required**
  Unique identifier of the source.

- **`ingest_key_id`** `string` -- **Required**
  Unique identifier of the ingest key.

### Response

Ingest key deleted

```ts
{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}
```

### Comments

- Deletion is immediate. Anything still sending with this key starts failing straight away.