# List subjects and versions

Source: https://convergingthought.com/docs/api-reference/subjects

> GET /v1/subjects — inspect the active route and recent retained adapters.



Requires `read`. This endpoint returns subjects in the selected tenant of the authenticated project, each with its active version, revision, and recent adapter metadata. It does not expose provider checkpoint paths or source passages.

```bash
curl --fail-with-body "$INTERNALIZE_BASE_URL/v1/subjects" \
  -H "Authorization: Bearer $INTERNALIZE_API_KEY"
```

## Response [#response]

```json
{
  "data": [
    {
      "id": "support-policy",
      "active_version": "YOUR_VERSION_ID",
      "revision": 1,
      "versions": [
        {
          "id": "YOUR_VERSION_ID",
          "created_at": "2026-09-24T10:00:00.000Z",
          "expires_at": "2026-09-25T10:00:00.000Z",
          "validation": { "passed": 8, "total": 8 },
          "source_job": "YOUR_LEARNING_JOB_ID"
        }
      ]
    }
  ]
}
```

The example uses illustrative timestamps and validation counts. Retention deadlines come from confirmed checkpoint state and should not be inferred from this example's one-day interval.

## Subject fields [#subject-fields]

`tenant_id` identifies the customer, or is `null` for the project namespace. `id` is the subject name you supplied, not an internal database ID. `active_version` is a version ID or `null` when the subject uses base. `revision` increments when activation changes the route. It is not a monotonically increasing adapter version number and does not tell you how many candidates were trained.

`versions` contains up to the 50 most recent saved versions for that subject, newest first. A saved version can be inactive because activation was disabled, another update won a race, or a different version was activated later.

## Version fields [#version-fields]

The version's `id` is the public value accepted by the activation endpoint. `created_at` and `expires_at` are ISO UTC timestamps. `validation.passed` and `validation.total` are integer counts; unlike a job's validation result, `passed` here is not a boolean.

`source_job` links the version to the internalization that created it. Read that job to inspect the original activation outcome and settled charge. The adapter's parent is recorded as `adapter_version` on the source job.

## Bounded listing [#bounded-listing]

The endpoint returns up to 100 subjects and 50 recent versions per subject. Select a namespace with `X-Internalize-Tenant`; a restricted key selects its bound tenant automatically. Without either, only the separate project namespace is listed. It has no pagination or additional filtering parameters. Do not treat an absent older version as proof of deletion or expiration; an active version can fall outside the recent-version window after many other candidates are saved.

Keep the version IDs and source job IDs important to your own release history. If you outgrow the current listing bounds, contact support rather than scraping private console internals.

## Activation workflow [#activation-workflow]

Read `active_version`, select the candidate to deploy, and send both to [Activate an adapter](/docs/api-reference/activation). The expected version guards against a concurrent release between the read and write. Reading the subject does not lock it.

There is no separate public create, rename, merge, or delete subject endpoint. The first admitted model operation creates a missing subject. See [Projects and subjects](/docs/concepts/subjects) before choosing the identity scheme for your application.