# Resources

6 operations on the Logion v1 API.

- [List resources](#list-resources) — `GET /v1/resources`
- [Get resource by ID](#get-resource-by-id) — `GET /v1/resources/{resource_id}`
- [List resource versions](#list-resource-versions) — `GET /v1/resources/{resource_id}/versions`
- [Build an acquisition plan for a resource version](#build-an-acquisition-plan-for-a-resource-version) — `GET /v1/resources/{resource_id}/versions/{version_id}/acquisition-plan`
- [Create a short-lived download manifest for a Logion bundle](#create-a-short-lived-download-manifest-for-a-logion-bundle) — `POST /v1/resources/{resource_id}/versions/{version_id}/download`
- [Ingest AI Catalog entries as resources](#ingest-ai-catalog-entries-as-resources) — `POST /v1/resources:ingest-catalog`

## List resources

```http
GET /v1/resources
```

List resources ordered by (created_at DESC, id DESC) with cursor
pagination.  Gated on the resource_read_surface feature flag.

Operation id: `list_resources`

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `resource_type` | query | string, optional | no |
| `lifecycle_status` | query | string, optional | no |
| `cursor` | query | string, optional | no |
| `limit` | query | integer | no |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Paginated list of resources | `ListResourcesResponse` |
| `403` | Feature flag disabled | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `ListResourcesResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `items` | ResourceSummary[] | yes |  |
| `next_cursor` | string, optional | no |  |

## Get resource by ID

```http
GET /v1/resources/{resource_id}
```

Retrieve a single resource by its ID.

Gated on the resource_read_surface feature flag.

Operation id: `get_resource`

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `resource_id` | path | string(uuid) | yes |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Resource found | `GetResourceResponse` |
| `403` | Feature flag disabled | `ErrorResponse` |
| `404` | Resource not found | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `GetResourceResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `projections` | ResourceProjections[] | no |  |
| `resource` | ResourceDetail | yes |  |
| `sources` | ResourceSources[] | no |  |

## List resource versions

```http
GET /v1/resources/{resource_id}/versions
```

List versions for a resource, newest first.

Gated on the resource_read_surface feature flag.

Operation id: `list_resource_versions`

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `resource_id` | path | string(uuid) | yes |
| `limit` | query | integer | no |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | List of versions for the resource | `ListResourceVersionsResponse` |
| `403` | Feature flag disabled | `ErrorResponse` |
| `404` | Resource not found | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `ListResourceVersionsResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `items` | ResourceVersionSummary[] | yes |  |

## Build an acquisition plan for a resource version

```http
GET /v1/resources/{resource_id}/versions/{version_id}/acquisition-plan
```

Return the server-owned acquisition plan for a resource version.

Gated on the resource_read_surface feature flag. Never receives or
returns local paths, scope identifiers, or installation identifiers.

Operation id: `get_acquisition_plan`

Takes an [`Authorization`](/docs/api/overview#authentication) header.

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `resource_id` | path | string(uuid) | yes |
| `version_id` | path | string(uuid) | yes |
| `channel` | query | string, optional | no |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Acquisition plan | `GetAcquisitionPlanResponse` |
| `402` | Entitlement required | `ErrorResponse` |
| `403` | Feature flag disabled or delivery forbidden | `ErrorResponse` |
| `404` | Resource version or distribution not found | `ErrorResponse` |
| `409` | Digest missing | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `GetAcquisitionPlanResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `alternatives` | string[] | no |  |
| `content_digest` | string | yes |  |
| `distribution_id` | string(uuid) | yes |  |
| `entitlement` | object | no |  |
| `expected` | object | no |  |
| `integrity` | object | no |  |
| `license` | object | no |  |
| `native` | object | no |  |
| `permissions` | object | no |  |
| `resource_id` | string(uuid) | yes |  |
| `selected_channel` | string | yes |  |
| `version_id` | string(uuid) | yes |  |
| `warnings` | string[] | no |  |

## Create a short-lived download manifest for a Logion bundle

```http
POST /v1/resources/{resource_id}/versions/{version_id}/download
```

Mint presigned URLs for an authorized Logion-hosted bundle.

Operation id: `create_artifact_download`

Takes an [`Authorization`](/docs/api/overview#authentication) header.

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `resource_id` | path | string(uuid) | yes |
| `version_id` | path | string(uuid) | yes |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Download manifest | `CreateArtifactDownloadResponse` |
| `401` | Unauthorized | `ErrorResponse` |
| `402` | Entitlement required | `ErrorResponse` |
| `403` | Forbidden or feature flag disabled | `ErrorResponse` |
| `404` | Resource version or bundle not found | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `CreateArtifactDownloadResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `channel` | string | yes |  |
| `distribution_id` | string(uuid) | yes |  |
| `expires_in_seconds` | integer | yes |  |
| `files` | ArtifactFile[] | no |  |
| `resource_id` | string(uuid) | yes |  |
| `version_id` | string(uuid) | yes |  |

## Ingest AI Catalog entries as resources

```http
POST /v1/resources:ingest-catalog
```

Record catalog entries as resources with catalog provenance.

Gated on the ``ai_catalog.ingestion`` feature flag.

Operation id: `ingest_catalog_entries`

Takes an [`Authorization`](/docs/api/overview#authentication) header.

**Request body**

Body `IngestCatalogEntriesRequest`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `entries` | CatalogEntryInput[] | no |  |
| `source_kind` | string | no | default `"ai_catalog_entry"`; max length 32 |
| `source_uri` | string | yes | max length 2048 |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Ingestion result | `IngestCatalogEntriesResponse` |
| `401` | Unauthorized | `ErrorResponse` |
| `403` | AI Catalog ingestion is disabled | `ErrorResponse` |
| `422` | Too many entries | `ErrorResponse` |

Returns `IngestCatalogEntriesResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `created` | integer | no | default `0` |
| `matched` | integer | no | default `0` |
| `new_versions` | integer | no | default `0` |
| `quarantine` | QuarantinedEntry[] | no |  |
| `results` | IngestedEntry[] | no |  |