> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doomberg.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider endpoints

> List and manage data provider connections and dataset snapshots — credentials are never exposed.

Providers are connections to external data sources (Polygon, FMP, AlphaVantage, etc.). Ithaca stores connection metadata and the latest dataset snapshot, but **credentials are never exposed** through the API.

## List providers

```http theme={null}
GET /api/providers
Authorization: Bearer <token>
```

Returns all provider connections for the tenant plus their latest snapshots.

### Response

```json theme={null}
{
  "providers": [
    {
      "id": "prov_abc",
      "kind": "polygon",
      "label": "Polygon production",
      "status": "ok",
      "last_sync_at": "2025-01-15T11:00:00Z",
      "snapshot": {
        "dataset": "polygon.ohlcv",
        "as_of": "2025-01-15T11:00:00Z",
        "row_count": 1240000
      }
    }
  ]
}
```

<Callout type="warn">
  Provider responses **never** include credentials. The `api_key` or `secret` used to authenticate with the upstream provider is stored encrypted and is write-only from the API's perspective.
</Callout>

## Create or upsert a provider

```http theme={null}
POST /api/providers
Authorization: Bearer <token>
Content-Type: application/json
```

```json theme={null}
{
  "kind": "polygon",
  "label": "Polygon production",
  "credentials": { "api_key": "abc123..." }
}
```

| Field         | Type   | Required | Description                                             |
| ------------- | ------ | -------- | ------------------------------------------------------- |
| `kind`        | string | yes      | Provider type (`polygon`, `fmp`, ...).                  |
| `label`       | string | yes      | Human-readable label.                                   |
| `credentials` | object | yes      | Upstream credentials. Stored encrypted; never returned. |

If a provider with the same `kind` + `label` exists, it is upserted (credentials replaced). Requires the `providers:write` scope.

### Response

```json theme={null}
{
  "id": "prov_abc",
  "kind": "polygon",
  "label": "Polygon production",
  "status": "ok",
  "created_at": "2025-01-15T12:00:00Z"
}
```

Note: `credentials` is **not** in the response.

## List dataset snapshots

```http theme={null}
GET /api/dataset-snapshots
Authorization: Bearer <token>
```

Returns the dataset snapshots Ithaca has recorded for the tenant's providers. A snapshot is a point-in-time record of what data was available.

### Response

```json theme={null}
{
  "snapshots": [
    {
      "id": "snap_001",
      "dataset": "polygon.ohlcv",
      "provider_id": "prov_abc",
      "as_of": "2025-01-15T11:00:00Z",
      "row_count": 1240000,
      "hash": "sha256:1a2b..."
    }
  ]
}
```

## Security

* Credentials are stored encrypted at rest.
* The API never returns credentials, even to the principal that created them.
* Credential updates are auditable (who, when) but the credential value itself is not logged.

## Related

* [Scopes](/api/overview) — the `providers:write` capability
* [Tenant isolation](/api/overview) — providers are tenant-scoped