# Create an internalization

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

> POST /v1/internalizations — learn a passage into a new adapter candidate.



Requires the `internalize` scope and an `Idempotency-Key`. The request creates a durable learning job for one subject. It does not return a completed adapter synchronously.

## Customer scope [#customer-scope]

Supply optional `tenant_id` in the body or `X-Internalize-Tenant` in the headers. If both are present they must match. A tenant-restricted key supplies its own tenant when omitted and rejects another tenant. Without either, an unrestricted key uses the separate project namespace. Use the same tenant for learning, inference, job reads, and version changes. See [Serve multiple customers](/docs/guides/multitenancy).

## Request [#request]

```json
{
  "subject_id": "support-policy",
  "content": "Northstar accepts returns within 30 days of delivery. Return labels are prepaid. Items marked final sale cannot be returned.",
  "max_cost_microusd": 5000000,
  "activate": true
}
```

| Field               | Type    | Required | Behavior                                                |
| ------------------- | ------- | -------- | ------------------------------------------------------- |
| `subject_id`        | string  | Yes      | Stable subject in the authenticated project             |
| `content`           | string  | Yes      | Self-contained source, length 20–16,000                 |
| `max_cost_microusd` | integer | Yes      | Total budget, $1–$100, including initial hosting        |
| `activate`          | boolean | No       | Defaults to `true`; attempt activation after validation |

The content is a string, not a file upload, URL-fetch instruction, message array, or embedding. Include the actual knowledge and the definitions needed to interpret it. The API does not accept a model selector, training hyperparameters, custom validation arrays, or additional metadata fields.

## Example [#example]

```bash
curl --fail-with-body "$INTERNALIZE_BASE_URL/v1/internalizations" \
  -H "Authorization: Bearer $INTERNALIZE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: northstar-policy-release-001" \
  --data '{
    "subject_id": "support-policy",
    "content": "Northstar accepts returns within 30 days of delivery. Return labels are prepaid. Items marked final sale cannot be returned.",
    "max_cost_microusd": 5000000,
    "activate": false
  }'
```

Use `activate: false` when the candidate needs an explicit release decision. You can evaluate a retained candidate by pinning its `adapter_version` for the same tenant and subject before deciding to activate it.

## Admission response [#admission-response]

New work returns `202`. An identical idempotent replay returns `200`:

```json
{ "id": "YOUR_JOB_ID", "status_url": "/v1/jobs/YOUR_JOB_ID" }
```

The request reserves `max_cost_microusd`, a required integer from 1,000,000 to 100,000,000 ($1–$100). This caps compute and initial 24-hour hosting together. It captures the subject's active adapter as the parent, or `base` for a clean subject. The project must have sufficient available balance and monthly capacity before work is admitted.

## Result [#result]

Poll the job with the same learning key, or a project key with `read` scope. A successful saved candidate has `status: "ready"` and a result shaped like this illustrative example:

```json
{
  "candidate": { "version_id": "YOUR_VERSION_ID" },
  "validation": { "passed": true, "passed_count": 8, "total_count": 8 },
  "activated": true,
  "activation_conflict": false
}
```

`ready` is learning success, while `activated` is the routing outcome. If another activation changed the parent during training, the candidate is saved but does not automatically replace that newer state. Inspect the subject and decide whether to activate manually.

## Failures and charges [#failures-and-charges]

A failed validation produces `rejected` and leaves the active version unchanged. A known execution error produces `failed`; read `error.code`. There is no fixed fee. Completed compute is charged for rejected candidates, budget exhaustion, and known learning outcomes. Our infrastructure failures are waived. A ready candidate also incurs verified hosting, even if activation was disabled or conflicted; see [billing](/docs/billing).

An ambiguous outcome can produce `reconciliation_required`, with the reservation held until evidence is recovered. Do not submit the same learning intent with a new idempotency key. See [job recovery](/docs/troubleshooting/jobs).

The current hosted preview returns `execution_unavailable` before executing model work. For enabled projects, follow [knowledge preparation](/docs/guides/knowledge) and [evaluation](/docs/guides/evaluation) to judge the resulting behavior.