{ "openapi": "3.1.0", "info": { "title": "Jean Behavioral API", "version": "0.1.0-beta", "description": "Beta contract. Enablement and base URL are provisioned per workspace. Examples are illustrative; this document does not assert that all operations are deployed.", "contact": { "email": "jonathan@jeantechnologies.com" } }, "servers": [ { "url": "https://{host}/v1", "description": "Replace host with the API host provided during onboarding.", "variables": { "host": { "default": "api.example.invalid" } } } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Data" }, { "name": "Models" }, { "name": "Semantic IDs" }, { "name": "Adaptation" }, { "name": "Simulation" }, { "name": "Jobs" } ], "paths": { "/datasets": { "get": { "operationId": "listDatasets", "summary": "List datasets", "description": "Discover datasets visible to your workspace. Access terms determine whether each dataset can be exported or used for training.", "tags": [ "Data" ], "x-doc-page": "list-datasets", "x-beta": true, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetList" }, "example": { "data": [ { "id": "ds_demo_v1", "name": "store-sample", "version": "1", "source": "workspace_upload", "access": { "export": true, "training": true }, "terms": "Workspace-provided data under the agreed pilot scope.", "item_count": 3, "event_count": 1, "request_id": "req_demo" } ], "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "minLength": 1 } } ] }, "post": { "operationId": "createDataset", "summary": "Import dataset", "description": "Create an immutable snapshot from a JSON sample. Maximum body size: 1 MiB. Reject duplicate IDs and unresolved item references. A successful job returns the validated dataset.", "tags": [ "Data" ], "x-doc-page": "create-dataset", "x-beta": true, "responses": { "202": { "description": "Accepted; poll the returned job ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_demo", "kind": "dataset_import", "status": "queued", "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Unique per workspace and endpoint. Retained for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDataset" }, "example": { "name": "store-sample", "items": [ { "item_id": "sku_42", "text": "Merino hiking socks" }, { "item_id": "sku_43", "text": "Wool trail socks" }, { "item_id": "sku_44", "text": "Light running socks" } ], "events": [ { "event_id": "evt_1", "person_id": "person_7", "item_id": "sku_42", "kind": "purchase", "timestamp": "2026-09-01T12:00:00Z", "value": 1 } ] } } } } } }, "/datasets/{dataset_id}": { "get": { "operationId": "getDataset", "summary": "Get dataset", "description": "Read source, version, size, and access terms for a dataset. This returns metadata, not person-level records.", "tags": [ "Data" ], "x-doc-page": "get-dataset", "x-beta": true, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" }, "example": { "id": "ds_demo_v1", "name": "store-sample", "version": "1", "source": "workspace_upload", "access": { "export": true, "training": true }, "terms": "Workspace-provided data under the agreed pilot scope.", "item_count": 3, "event_count": 1, "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "parameters": [ { "in": "path", "name": "dataset_id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } } ] } }, "/datasets/{dataset_id}/exports": { "post": { "operationId": "exportDataset", "summary": "Export dataset", "description": "Request an authorized JSONL export. Poll the job for a download URL and its expiry. Rows are tagged as item or event and preserve the dataset schema.", "tags": [ "Data" ], "x-doc-page": "export-dataset", "x-beta": true, "responses": { "202": { "description": "Accepted; poll the returned job ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_demo", "kind": "dataset_export", "status": "queued", "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "parameters": [ { "in": "path", "name": "dataset_id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Unique per workspace and endpoint. Retained for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" }, "example": { "format": "jsonl" } } } } } }, "/models": { "get": { "operationId": "listModels", "summary": "List models", "description": "List model deployments visible to your key. Only ready models accept inference. Capabilities describe enabled operations, not future roadmap features.", "tags": [ "Models" ], "x-doc-page": "list-models", "x-beta": true, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" }, "example": { "data": [ { "id": "mdl_demo_v1", "family": "jean-rec-1", "version": "1", "architecture": "sasrec", "training_method": "trained_from_scratch", "status": "ready", "capabilities": [ "predict", "embed" ], "dataset_id": "ds_demo_v1", "max_history_items": 20, "embedding_dimensions": 64, "evaluation": "Illustrative card. Actual deployments include dataset, temporal split, baselines, and measured metrics.", "request_id": "req_demo" } ], "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "minLength": 1 } } ] } }, "/models/{model_id}": { "get": { "operationId": "getModel", "summary": "Get model", "description": "Read a pinned deployment card. Tokenizer compatibility, history limits, and supported capabilities belong to this version.", "tags": [ "Models" ], "x-doc-page": "get-model", "x-beta": true, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" }, "example": { "id": "mdl_demo_v1", "family": "jean-rec-1", "version": "1", "architecture": "sasrec", "training_method": "trained_from_scratch", "status": "ready", "capabilities": [ "predict", "embed" ], "dataset_id": "ds_demo_v1", "max_history_items": 20, "embedding_dimensions": 64, "evaluation": "Illustrative card. Actual deployments include dataset, temporal split, baselines, and measured metrics.", "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } } ] } }, "/models/{model_id}/predict": { "post": { "operationId": "predict", "summary": "Predict", "description": "Rank supplied candidates for a history. All IDs must belong to the model catalog. Scores are relative and not calibrated probabilities. Returns up to limit items; ties break by item ID.", "tags": [ "Models" ], "x-doc-page": "predict", "x-beta": true, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Prediction" }, "example": { "model_id": "mdl_demo_v1", "model_version": "1", "items": [ { "item_id": "sku_43", "score": 2.1 }, { "item_id": "sku_44", "score": 1.4 } ], "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PredictRequest" }, "example": { "history": [ "sku_42" ], "candidate_item_ids": [ "sku_43", "sku_44" ], "limit": 2 } } } } } }, "/models/{model_id}/embed": { "post": { "operationId": "embed", "summary": "Embed", "description": "Encode a history using a model with the embed capability. Vector size and geometry belong to this model version. Do not compare vectors from different versions without alignment.", "tags": [ "Models" ], "x-doc-page": "embed", "x-beta": true, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Embedding" }, "example": { "model_id": "mdl_demo_v1", "model_version": "1", "embedding": [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ], "dimensions": 64, "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedRequest" }, "example": { "history": [ "sku_42" ] } } } } } }, "/tokenizers": { "post": { "operationId": "fitTokenizer", "summary": "Fit tokenizer", "description": "Fit a text tokenizer on an approved dataset catalog. The job returns a ready tokenizer with its measured layout and collision diagnostics. Settings are selected for the catalog during the beta.", "tags": [ "Semantic IDs" ], "x-doc-page": "fit-tokenizer", "x-beta": true, "responses": { "202": { "description": "Accepted; poll the returned job ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_demo", "kind": "tokenizer_fit", "status": "queued", "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Unique per workspace and endpoint. Retained for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FitTokenizer" }, "example": { "dataset_id": "ds_catalog_v1", "name": "catalog-v1" } } } } } }, "/tokenizers/{tokenizer_id}": { "get": { "operationId": "getTokenizer", "summary": "Get tokenizer", "description": "Read the immutable tokenizer version and fit diagnostics. The code array has semantic_levels semantic codes followed by one collision suffix.", "tags": [ "Semantic IDs" ], "x-doc-page": "get-tokenizer", "x-beta": true, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tokenizer" }, "example": { "id": "tok_demo_v1", "dataset_id": "ds_catalog_v1", "version": "1", "status": "ready", "encoder": "sentence-transformers/all-MiniLM-L6-v2", "semantic_levels": 8, "codebook_size": 1024, "collision_rate": 0.0073, "suffix": "collision_index", "item_count": 69629, "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "parameters": [ { "in": "path", "name": "tokenizer_id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } } ] } }, "/tokenizers/{tokenizer_id}/exports": { "post": { "operationId": "exportTokenizer", "summary": "Export tokenizer", "description": "Export an authorized bundle containing manifest.json, encoder identity, codebooks, item-to-code mapping, token layout, and checksums. Poll the job for the download URL. Encoder weights require their own license and are not implicitly included.", "tags": [ "Semantic IDs" ], "x-doc-page": "export-tokenizer", "x-beta": true, "responses": { "202": { "description": "Accepted; poll the returned job ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_demo", "kind": "tokenizer_export", "status": "queued", "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "parameters": [ { "in": "path", "name": "tokenizer_id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Unique per workspace and endpoint. Retained for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenizerExportRequest" }, "example": { "format": "bundle" } } } } } }, "/semantic-ids": { "post": { "operationId": "assignSemanticIds", "summary": "Read semantic IDs", "description": "Look up item codes in a ready tokenizer. This operation does not add items or refit the vocabulary. Unknown items fail the whole request with 422.", "tags": [ "Semantic IDs" ], "x-doc-page": "assign-semantic-ids", "x-beta": true, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemanticIds" }, "example": { "tokenizer_id": "tok_demo_v1", "data": [ { "item_id": "sku_42", "codes": [ 17, 204, 8, 91, 3, 12, 44, 6, 0 ] } ], "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignSemanticIds" }, "example": { "tokenizer_id": "tok_demo_v1", "item_ids": [ "sku_42" ] } } } } } }, "/generate": { "post": { "operationId": "generate", "summary": "Generate", "description": "Retrieve items using a model with the generate capability and its exact tokenizer version. Output IDs resolve to that catalog. Returns up to limit items; an empty eligible catalog returns 422. Scores are relative, not calibrated probabilities.", "tags": [ "Semantic IDs" ], "x-doc-page": "generate", "x-beta": true, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" }, "example": { "model_id": "mdl_sid_demo_v1", "model_version": "1", "tokenizer_id": "tok_demo_v1", "items": [ { "item_id": "sku_43", "score": -3.2 } ], "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateRequest" }, "example": { "model_id": "mdl_sid_demo_v1", "tokenizer_id": "tok_demo_v1", "history": [ "sku_42" ], "limit": 10, "exclude_history": true } } } } } }, "/adaptations": { "post": { "operationId": "createAdaptation", "summary": "Adapt model", "description": "Request managed next-item adaptation. The base model must be an enabled adaptation source. A successful job returns a candidate model and evaluation summary; activation follows review. It does not replace the base deployment.", "tags": [ "Adaptation" ], "x-doc-page": "create-adaptation", "x-beta": true, "responses": { "202": { "description": "Accepted; poll the returned job ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_demo", "kind": "adaptation", "status": "queued", "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Unique per workspace and endpoint. Retained for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdaptationRequest" }, "example": { "base_model_id": "mdl_base_beta", "dataset_id": "ds_catalog_v1", "tokenizer_id": "tok_demo_v1", "objective": "next_item" } } } } } }, "/simulations": { "post": { "operationId": "createSimulation", "summary": "Create simulation", "description": "Sample next-item sequences for a supplied population. Requires simulate capability. Person IDs must be unique within the request; candidate IDs must belong to the model catalog. Steps are interactions, not time. The same seed is reproducible within a pinned model and runtime.", "tags": [ "Simulation" ], "x-doc-page": "create-simulation", "x-beta": true, "responses": { "202": { "description": "Accepted; poll the returned job ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_demo", "kind": "simulation", "status": "queued", "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Unique per workspace and endpoint. Retained for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulationRequest" }, "example": { "model_id": "mdl_sim_demo_v1", "population": [ { "person_id": "person_7", "history": [ "sku_42" ] } ], "candidate_item_ids": [ "sku_43", "sku_44" ], "steps": 5, "trajectories_per_person": 1, "repeat_policy": "allow", "seed": 42 } } } } } }, "/jobs/{job_id}": { "get": { "operationId": "getJob", "summary": "Get job", "description": "Poll asynchronous work. A succeeded job returns its typed result; a failed job returns error. Simulation results are model samples. Dataset and tokenizer exports return expiring download URLs. Job records expire after seven days.", "tags": [ "Jobs" ], "x-doc-page": "get-job", "x-beta": true, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_demo", "kind": "simulation", "status": "succeeded", "result": { "model_id": "mdl_sim_demo_v1", "model_version": "1", "seed": 42, "repeat_policy": "allow", "trajectories": [ { "person_id": "person_7", "sample": 0, "item_ids": [ "sku_43", "sku_44", "sku_43", "sku_44", "sku_43" ], "stop_reason": "completed" } ], "interpretation": "model_samples" }, "request_id": "req_demo" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RetryError" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/RetryError" } }, "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } } ] } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "ErrorResponse": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" }, "request_id": { "type": "string", "description": "Request identifier for support.", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } }, "required": [ "error", "request_id" ] }, "Item": { "type": "object", "additionalProperties": false, "properties": { "item_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "text": { "type": "string", "description": "Title and description for text tokenization.", "minLength": 1, "maxLength": 10000 } }, "required": [ "item_id", "text" ] }, "Event": { "type": "object", "additionalProperties": false, "properties": { "event_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "person_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "item_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "kind": { "type": "string", "minLength": 1, "maxLength": 64 }, "timestamp": { "type": "string", "description": "UTC timestamp for the observed action.", "format": "date-time", "pattern": "Z$" }, "value": { "type": "number" } }, "required": [ "event_id", "person_id", "item_id", "kind", "timestamp" ] }, "CreateDataset": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" }, "minItems": 1, "maxItems": 1000 }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" }, "minItems": 0, "maxItems": 5000 } }, "required": [ "name", "items" ] }, "Dataset": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "name": { "type": "string" }, "version": { "type": "string" }, "source": { "type": "string" }, "access": { "type": "object", "additionalProperties": false, "properties": { "export": { "type": "boolean" }, "training": { "type": "boolean" } }, "required": [ "export", "training" ] }, "terms": { "type": "string", "description": "Applicable source and workspace access terms." }, "item_count": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "event_count": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "request_id": { "type": "string", "description": "Request identifier for support.", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } }, "required": [ "id", "name", "version", "source", "access", "terms", "item_count", "event_count", "request_id" ] }, "DatasetList": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Dataset" }, "minItems": 0, "maxItems": 100 }, "next_cursor": { "type": "string", "minLength": 1 }, "request_id": { "type": "string", "description": "Request identifier for support.", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } }, "required": [ "data", "request_id" ] }, "FitTokenizer": { "type": "object", "additionalProperties": false, "properties": { "dataset_id": { "type": "string", "description": "Immutable dataset snapshot containing the catalog.", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "dataset_id" ] }, "Tokenizer": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "dataset_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "version": { "type": "string" }, "status": { "type": "string", "enum": [ "ready" ] }, "encoder": { "type": "string" }, "semantic_levels": { "type": "integer", "minimum": 1, "maximum": 64 }, "codebook_size": { "type": "integer", "minimum": 2, "maximum": 65536 }, "collision_rate": { "type": "number", "minimum": 0, "maximum": 1 }, "suffix": { "type": "string", "enum": [ "collision_index" ] }, "item_count": { "type": "integer", "minimum": 1, "maximum": 1000000000 }, "request_id": { "type": "string", "description": "Request identifier for support.", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } }, "required": [ "id", "dataset_id", "version", "status", "encoder", "semantic_levels", "codebook_size", "collision_rate", "suffix", "item_count", "request_id" ] }, "AssignSemanticIds": { "type": "object", "additionalProperties": false, "properties": { "tokenizer_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "item_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "minItems": 1, "maxItems": 1000, "uniqueItems": true, "description": "Items already in this tokenizer snapshot. No implicit catalog insertion." } }, "required": [ "tokenizer_id", "item_ids" ] }, "SemanticId": { "type": "object", "additionalProperties": false, "properties": { "item_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "codes": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "minItems": 2, "maxItems": 65 } }, "required": [ "item_id", "codes" ] }, "SemanticIds": { "type": "object", "additionalProperties": false, "properties": { "tokenizer_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SemanticId" }, "minItems": 1, "maxItems": 1000 }, "request_id": { "type": "string", "description": "Request identifier for support.", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } }, "required": [ "tokenizer_id", "data", "request_id" ] }, "ExportRequest": { "type": "object", "additionalProperties": false, "properties": { "format": { "type": "string", "enum": [ "jsonl" ], "default": "jsonl" } }, "required": [] }, "TokenizerExportRequest": { "type": "object", "additionalProperties": false, "properties": { "format": { "type": "string", "enum": [ "bundle" ], "default": "bundle" } }, "required": [] }, "Export": { "type": "object", "additionalProperties": false, "properties": { "resource_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "format": { "type": "string", "enum": [ "jsonl", "bundle" ] }, "download_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "resource_id", "format", "download_url", "expires_at", "sha256" ] }, "Model": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "family": { "type": "string" }, "version": { "type": "string" }, "architecture": { "type": "string" }, "training_method": { "type": "string", "enum": [ "pretrained", "adapted", "trained_from_scratch" ] }, "status": { "type": "string", "enum": [ "candidate", "ready", "unavailable" ] }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "predict", "embed", "generate", "simulate" ] }, "minItems": 0, "maxItems": 4, "uniqueItems": true }, "dataset_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "tokenizer_id": { "type": "string", "description": "Required for Semantic ID generation; absent for item-index models.", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "max_history_items": { "type": "integer", "minimum": 1, "maximum": 100000 }, "embedding_dimensions": { "type": "integer", "minimum": 1, "maximum": 100000 }, "evaluation": { "type": "string", "description": "Observed evaluation summary, including limitations." }, "request_id": { "type": "string", "description": "Request identifier for support.", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } }, "required": [ "id", "family", "version", "architecture", "training_method", "status", "capabilities", "dataset_id", "max_history_items", "evaluation", "request_id" ] }, "ModelList": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" }, "minItems": 0, "maxItems": 100 }, "next_cursor": { "type": "string", "minLength": 1 }, "request_id": { "type": "string", "description": "Request identifier for support.", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } }, "required": [ "data", "request_id" ] }, "PredictRequest": { "type": "object", "additionalProperties": false, "properties": { "history": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "minItems": 1, "maxItems": 1000, "description": "Item IDs from the model catalog, oldest first. Repeats are allowed. The model card may set a lower limit." }, "candidate_item_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "minItems": 1, "maxItems": 1000, "uniqueItems": true, "description": "Eligible items from the model catalog." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, "required": [ "history", "candidate_item_ids" ] }, "RankedItem": { "type": "object", "additionalProperties": false, "properties": { "item_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "score": { "type": "number", "description": "Relative ranking score, not a calibrated event probability." } }, "required": [ "item_id", "score" ] }, "Prediction": { "type": "object", "additionalProperties": false, "properties": { "model_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "model_version": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/RankedItem" }, "minItems": 1, "maxItems": 100 }, "request_id": { "type": "string", "description": "Request identifier for support.", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } }, "required": [ "model_id", "model_version", "items", "request_id" ] }, "EmbedRequest": { "type": "object", "additionalProperties": false, "properties": { "history": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "minItems": 1, "maxItems": 1000, "description": "Item IDs from the model catalog, oldest first. Repeats are allowed. The model card may set a lower limit." } }, "required": [ "history" ] }, "Embedding": { "type": "object", "additionalProperties": false, "properties": { "model_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "model_version": { "type": "string" }, "embedding": { "type": "array", "items": { "type": "number" }, "minItems": 1, "maxItems": 100000 }, "dimensions": { "type": "integer", "minimum": 1, "maximum": 100000 }, "request_id": { "type": "string", "description": "Request identifier for support.", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } }, "required": [ "model_id", "model_version", "embedding", "dimensions", "request_id" ] }, "GenerateRequest": { "type": "object", "additionalProperties": false, "properties": { "model_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "tokenizer_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "history": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "minItems": 1, "maxItems": 1000, "description": "Item IDs from the model catalog, oldest first. Repeats are allowed. The model card may set a lower limit." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "exclude_history": { "type": "boolean", "default": true } }, "required": [ "model_id", "tokenizer_id", "history" ] }, "Generation": { "type": "object", "additionalProperties": false, "properties": { "model_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "model_version": { "type": "string" }, "tokenizer_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/RankedItem" }, "minItems": 1, "maxItems": 100 }, "request_id": { "type": "string", "description": "Request identifier for support.", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } }, "required": [ "model_id", "model_version", "tokenizer_id", "items", "request_id" ] }, "AdaptationRequest": { "type": "object", "additionalProperties": false, "properties": { "base_model_id": { "type": "string", "description": "A model enabled as an adaptation source.", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "dataset_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "tokenizer_id": { "type": "string", "description": "Required if adapting a Semantic ID model.", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "objective": { "type": "string", "enum": [ "next_item" ], "default": "next_item" } }, "required": [ "base_model_id", "dataset_id" ] }, "Actor": { "type": "object", "additionalProperties": false, "properties": { "person_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "history": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "minItems": 1, "maxItems": 1000, "description": "Item IDs from the model catalog, oldest first. Repeats are allowed. The model card may set a lower limit." } }, "required": [ "person_id", "history" ] }, "SimulationRequest": { "type": "object", "additionalProperties": false, "properties": { "model_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "population": { "type": "array", "items": { "$ref": "#/components/schemas/Actor" }, "minItems": 1, "maxItems": 20 }, "candidate_item_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "minItems": 1, "maxItems": 1000, "uniqueItems": true, "description": "" }, "steps": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 }, "trajectories_per_person": { "type": "integer", "minimum": 1, "maximum": 5, "default": 1 }, "repeat_policy": { "type": "string", "enum": [ "allow", "exclude_history" ], "default": "allow" }, "seed": { "type": "integer", "minimum": 0, "maximum": 2147483647 } }, "required": [ "model_id", "population", "candidate_item_ids", "seed" ] }, "Trajectory": { "type": "object", "additionalProperties": false, "properties": { "person_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "sample": { "type": "integer", "minimum": 0, "maximum": 4 }, "item_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "minItems": 0, "maxItems": 10 }, "stop_reason": { "type": "string", "enum": [ "completed", "no_candidates" ] } }, "required": [ "person_id", "sample", "item_ids", "stop_reason" ] }, "SimulationResult": { "type": "object", "additionalProperties": false, "properties": { "model_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "model_version": { "type": "string" }, "seed": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "repeat_policy": { "type": "string", "enum": [ "allow", "exclude_history" ] }, "trajectories": { "type": "array", "items": { "$ref": "#/components/schemas/Trajectory" }, "minItems": 1, "maxItems": 100 }, "interpretation": { "type": "string", "enum": [ "model_samples" ] } }, "required": [ "model_id", "model_version", "seed", "repeat_policy", "trajectories", "interpretation" ] }, "Job": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "kind": { "type": "string", "enum": [ "dataset_import", "dataset_export", "tokenizer_fit", "tokenizer_export", "adaptation", "simulation" ] }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ] }, "result": { "oneOf": [ { "$ref": "#/components/schemas/Dataset" }, { "$ref": "#/components/schemas/Tokenizer" }, { "$ref": "#/components/schemas/Model" }, { "$ref": "#/components/schemas/Export" }, { "$ref": "#/components/schemas/SimulationResult" } ] }, "error": { "$ref": "#/components/schemas/Error" }, "request_id": { "type": "string", "description": "Request identifier for support.", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } }, "required": [ "id", "kind", "status", "request_id" ], "allOf": [ { "if": { "properties": { "status": { "const": "succeeded" } } }, "then": { "required": [ "result" ], "not": { "required": [ "error" ] } }, "else": { "not": { "required": [ "result" ] } } }, { "if": { "properties": { "status": { "const": "failed" } } }, "then": { "required": [ "error" ] }, "else": { "not": { "required": [ "error" ] } } } ] } }, "responses": { "Error": { "description": "Request failed. See the API overview for retry guidance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "invalid_request", "message": "Check the request fields." }, "request_id": "req_demo" } } } }, "RetryError": { "description": "Request failed. See the API overview for retry guidance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "invalid_request", "message": "Check the request fields." }, "request_id": "req_demo" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1, "maximum": 86400 } } } } } } }