Create an internalization
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
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.
Request
{
"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
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
New work returns 202. An identical idempotent replay returns 200:
{ "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
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:
{
"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
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.
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.
The current hosted preview returns execution_unavailable before executing model work. For enabled projects, follow knowledge preparation and evaluation to judge the resulting behavior.