# Sources

## Source Model

### Fields

- **`object`** `"source"`

- **`id`** `string`

   Unique identifier, prefixed with `src_`.

- **`project_id`** `string`

- **`project_name`** `string`

- **`name`** `string`

   Unique within its project.

- **`storage_gb`** `number`

   Data this source has ingested, in gigabytes of uncompressed data: collection files plus
   uploaded artifacts. Recalculated hourly.

- **`schema_count`** `number`

   How many schema versions this source has produced.

- **`collections_count`** `number`

   How many collections this source feeds.

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

   When the source is scheduled to be deleted; null when it is not.

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

- **`updated_at`** [`ISODateString`](/api/sources#iso-date-string)

### Referenced Types

#### ISODateString

`ISODateString`

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

## List Sources

### Endpoint

Retrieve a list of sources for a project.

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

**Scope:** `sources:read`

### Path Parameters

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

### Query Parameters

- **`order_by`** `string`
  Field used to order the sources. Optional. Defaults to `"name"`. Allowed values: `"created_at"`, `"name"`, `"updated_at"`.

- **`project_id`** `string`
  Filter to sources belonging to a single project. Optional.

- **`deleted_at`** [`NullableDateFilter`](/api/sources#nullable-date-filter)
  Filter by scheduled deletion date. Use `null` for sources that are not scheduled for deletion, `not:null` for sources that are. Optional.

- **`limit`** `number`
  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`
  Optional. Defaults to `"asc"`. Allowed values: `"asc"`, `"desc"`.

### Response

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

### Comments

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

## Retrieve Source

### Endpoint

Retrieve a single source.

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

**Scope:** `sources:read`

### Path Parameters

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

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

### Response

Source retrieved

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

## Create Source

### Endpoint

Create a source in a project.

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

**Scope:** `sources:write`

### Path Parameters

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

### Request Body

- **`name`** `string` -- **Required**
  Display name for the source. Minimum length: `1`. Maximum length: `128`.

- **`project_id`** `string`
  Project the source belongs to. Ignored when the nested path supplies it. Optional.

### Response

Source created

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

### Comments

- The project is supplied by the path.
- Source names are unique within a project.

## Update Source

### Endpoint

Update a source.

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

**Scope:** `sources:write`

### Path Parameters

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

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

### Request Body

- **`name`** `string`
  Display name for the source. Optional. Minimum length: `1`. Maximum length: `128`.

- **`deleted_at`** `null`
  Send `null` to restore a source that is scheduled for deletion. The deletion date itself is set by the delete endpoint and cannot be written here. Optional.

### Response

Source updated

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

### Comments

- Send `deleted_at` as `null` to restore a source that is scheduled for deletion.

## Delete Source

### Endpoint

Schedule a source for deletion.

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

**Scope:** `sources:delete`

### Path Parameters

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

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

### Response

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

### Comments

- The source is hidden immediately and permanently removed 7 days later. Restore it before then by updating it with `deleted_at` set to null.

## Force Delete Source

### Endpoint

Delete a source permanently, without waiting out its restore window.

```http
DELETE /v1/projects/:project_id/sources/:source_id/force
```

**Scope:** `sources:delete`

### Path Parameters

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

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

### Response

Source queued for permanent deletion.

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

### Comments

- Works on a live source as well as one already scheduled for deletion.
- Every collection, record and file under the source is destroyed immediately. Nothing here can be restored.