> This page is also available as Markdown: append .md to its URL. The full index of Sikaru docs is at https://docs.sikaru.ai/llms.txt. Code examples use only operations from the public API reference at https://docs.sikaru.ai/api-reference.

# Import End User State

POST https://api.sikaru.ai/v1/projects/{project_id}/managed-agents/{agent_slug}/end-users/{tenant_id}/{user_id}/imports
Content-Type: application/json

Import a versioned product snapshot atomically, preserving correction provenance.

The cell must already exist. Every file requires expectedEtag (null for an
absent destination). Reusing an importId requires the identical manifest.
The digest is SHA-256 of canonical JSON \{sourceRevision, files}, with sorted
keys, compact separators and the supplied file order. Private layers are
accepted as input but are never returned in the receipt or end-user view.

Reference: https://docs.sikaru.ai/api-reference/end-users/import-state

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `project_id` (string, required)
- `agent_slug` (string, required)
- `tenant_id` (string, required)
- `user_id` (string, required)

### Body (application/json)

This endpoint expects a CellImport.

- `digest` (string, required)
- `files` (list of ImportFile, required)
- `importId` (string, required)
- `sourceRevision` (string, required)

## Response

### 200

Successful Response

- `digest` (string, required)
- `importId` (string, required)
- `paths` (list of string, required)
- `sourceRevision` (string, required)
- `evaluationStatus` (enum, optional, nullable)
  - Allowed values: `ready`, `pending`, `unjudgeable`, `superseded`

## Errors

### 401 Unauthorized Error

Missing or invalid credentials (`unauthenticated`).

- `code` (string, required) — Stable machine code. Specific values: `credits_exhausted` (402): Your organization has no available credits. Add credits in Billing to continue.; `spend_limit_reached` (402): A spending limit has been reached. Review the organization's monthly limit and agent caps in Billing.; `billing_unavailable` (503): Spending confirmation is temporarily unavailable. Your progress is saved; retry shortly.; `idempotency_conflict` (409): the idempotency key was already used for a different request, or for a file that was deleted; `concurrent_request` (409): another request is changing the same resource; send the same request again; `agent_disabled` (409): the agent is turned off; turn it on before starting new work; `release_unavailable` (409): the agent has no release that can run; `action_not_pending` (409): the tool call or approval is not waiting for this input: it already has an outcome, its run finished, it is handled by Sikaru, or it does not match a pending request; `still_blocked` (409): funding still prevents this work from resuming; inspect reason; `not_resumable` (409): the run is not waiting for funding or has already resumed; `not_retryable` (409): the run cannot be retried: it did not fail, its failure is not recoverable, or it failed too long ago; `branch_unavailable` (409): the session cannot be branched at that run; `record_invalid` (409): the retained record cannot be read; `state_conflict` (409): the request conflicts with the resource's current state; read it before trying again; `agent_capacity_full` (429): the agent's turn capacity is full; `agent_unavailable` (503): execution is switched off for this agent; `turn_delivery_pending` (503): the message was recorded but has not started; send it again with the same idempotency key; `execution_storage_unavailable` (503): session, file or workspace storage is unavailable right now; `storage_unavailable` (503): the storage behind this resource is unavailable right now; `trajectory_storage_unavailable` (503): retained run records cannot be read right now; `top_up_unavailable` (409): agent credit top-ups are not available for this organization; `top_up_amount_out_of_range` (422): the amount must be whole cents within the per-top-up minimum and maximum; `top_up_blocked` (409): agent top-ups are paused for this organization until support clears them; `release_check_blocked` (409): a release check blocked this version; `detail` is an object with `message`, `publicationId` (the publication Publish Anyway releases) and `results`, one per Grader: `graderId`, `name`, `outcome` (`blocked` or `couldnt_verify`), `flagged` (up to 10 conversation keys flagged only for this version) and `flaggedCount`; `release_check_unverified` (409): a release check couldn't verify this version; `detail` is an object with `message`, `publicationId` (the publication Publish Anyway releases) and `results`, one per Grader: `graderId`, `name`, `outcome` (`blocked` or `couldnt_verify`), `flagged` (up to 10 conversation keys flagged only for this version) and `flaggedCount`; `invalid_grader_file` (422): a Grader file is invalid; `detail` names its path and line; `invalid_grader` (422): the Grader's criteria are invalid; `grader_admin_required` (403): changing a Grader's judge, escalation or release check, or removing a Grader file, needs Grader admin credentials; `grading_off` (409): personal and end-user agents are never graded; `reason_required` (409): turning off or loosening a release check that blocks a release needs a reason, given from the dashboard or the API; `release_check_refused` (409): the release check cannot be turned on: the Grader has no live version; `preset_judge_fixed` (409): built-in Graders keep the decision model and never escalate; `escalation_unavailable` (422): only a Grader judged by the decision model can escalate; `missing_field` (422): a required field for this request is missing; `judge_is_graded_agent` (409): an agent cannot judge its own conversations; `judge_content_private` (409): a personal or end-user agent cannot be a judge; `judge_not_live` (409): the judge agent needs a live version first; `judge_needs_setup` (409): the judge agent must be set up to read a copy of the conversation; `test_unavailable` (503): Grader testing is unavailable right now; `estimate_unavailable` (503): judge pricing is unavailable right now; `regrade_refused` (409): the Grader has no version, or the selected window has no or too many conversations; `regrade_unavailable` (503): history re-scoring is unavailable right now. Otherwise a status default: `bad_request` (400), `unauthenticated` (401), `payment_required` (402), `forbidden` (403), `not_found` (404), `method_not_allowed` (405), `not_acceptable` (406), `request_timeout` (408), `conflict` (409), `gone` (410), `length_required` (411), `precondition_failed` (412), `payload_too_large` (413), `unsupported_media_type` (415), `range_not_satisfiable` (416), `invalid_request` (422), `locked` (423), `precondition_required` (428), `rate_limited` (429), `internal_error` (500), `not_implemented` (501), `bad_gateway` (502), `service_unavailable` (503), `gateway_timeout` (504). `429` and `503` refusals with a specific code carry `Retry-After` in seconds.
- `detail` (ErrorResponseDetail, required)
- `reason` (string, optional, nullable) — Current funding reason when code is still_blocked.
- `topUp` (TopUpHint, optional, nullable) — Set on `credits_exhausted`, and on `still_blocked` with that reason, while agent top-ups are available.

### 403 Forbidden Error

The credential lacks access or a required scope (`forbidden`).

- `code` (string, required) — Stable machine code. Specific values: `credits_exhausted` (402): Your organization has no available credits. Add credits in Billing to continue.; `spend_limit_reached` (402): A spending limit has been reached. Review the organization's monthly limit and agent caps in Billing.; `billing_unavailable` (503): Spending confirmation is temporarily unavailable. Your progress is saved; retry shortly.; `idempotency_conflict` (409): the idempotency key was already used for a different request, or for a file that was deleted; `concurrent_request` (409): another request is changing the same resource; send the same request again; `agent_disabled` (409): the agent is turned off; turn it on before starting new work; `release_unavailable` (409): the agent has no release that can run; `action_not_pending` (409): the tool call or approval is not waiting for this input: it already has an outcome, its run finished, it is handled by Sikaru, or it does not match a pending request; `still_blocked` (409): funding still prevents this work from resuming; inspect reason; `not_resumable` (409): the run is not waiting for funding or has already resumed; `not_retryable` (409): the run cannot be retried: it did not fail, its failure is not recoverable, or it failed too long ago; `branch_unavailable` (409): the session cannot be branched at that run; `record_invalid` (409): the retained record cannot be read; `state_conflict` (409): the request conflicts with the resource's current state; read it before trying again; `agent_capacity_full` (429): the agent's turn capacity is full; `agent_unavailable` (503): execution is switched off for this agent; `turn_delivery_pending` (503): the message was recorded but has not started; send it again with the same idempotency key; `execution_storage_unavailable` (503): session, file or workspace storage is unavailable right now; `storage_unavailable` (503): the storage behind this resource is unavailable right now; `trajectory_storage_unavailable` (503): retained run records cannot be read right now; `top_up_unavailable` (409): agent credit top-ups are not available for this organization; `top_up_amount_out_of_range` (422): the amount must be whole cents within the per-top-up minimum and maximum; `top_up_blocked` (409): agent top-ups are paused for this organization until support clears them; `release_check_blocked` (409): a release check blocked this version; `detail` is an object with `message`, `publicationId` (the publication Publish Anyway releases) and `results`, one per Grader: `graderId`, `name`, `outcome` (`blocked` or `couldnt_verify`), `flagged` (up to 10 conversation keys flagged only for this version) and `flaggedCount`; `release_check_unverified` (409): a release check couldn't verify this version; `detail` is an object with `message`, `publicationId` (the publication Publish Anyway releases) and `results`, one per Grader: `graderId`, `name`, `outcome` (`blocked` or `couldnt_verify`), `flagged` (up to 10 conversation keys flagged only for this version) and `flaggedCount`; `invalid_grader_file` (422): a Grader file is invalid; `detail` names its path and line; `invalid_grader` (422): the Grader's criteria are invalid; `grader_admin_required` (403): changing a Grader's judge, escalation or release check, or removing a Grader file, needs Grader admin credentials; `grading_off` (409): personal and end-user agents are never graded; `reason_required` (409): turning off or loosening a release check that blocks a release needs a reason, given from the dashboard or the API; `release_check_refused` (409): the release check cannot be turned on: the Grader has no live version; `preset_judge_fixed` (409): built-in Graders keep the decision model and never escalate; `escalation_unavailable` (422): only a Grader judged by the decision model can escalate; `missing_field` (422): a required field for this request is missing; `judge_is_graded_agent` (409): an agent cannot judge its own conversations; `judge_content_private` (409): a personal or end-user agent cannot be a judge; `judge_not_live` (409): the judge agent needs a live version first; `judge_needs_setup` (409): the judge agent must be set up to read a copy of the conversation; `test_unavailable` (503): Grader testing is unavailable right now; `estimate_unavailable` (503): judge pricing is unavailable right now; `regrade_refused` (409): the Grader has no version, or the selected window has no or too many conversations; `regrade_unavailable` (503): history re-scoring is unavailable right now. Otherwise a status default: `bad_request` (400), `unauthenticated` (401), `payment_required` (402), `forbidden` (403), `not_found` (404), `method_not_allowed` (405), `not_acceptable` (406), `request_timeout` (408), `conflict` (409), `gone` (410), `length_required` (411), `precondition_failed` (412), `payload_too_large` (413), `unsupported_media_type` (415), `range_not_satisfiable` (416), `invalid_request` (422), `locked` (423), `precondition_required` (428), `rate_limited` (429), `internal_error` (500), `not_implemented` (501), `bad_gateway` (502), `service_unavailable` (503), `gateway_timeout` (504). `429` and `503` refusals with a specific code carry `Retry-After` in seconds.
- `detail` (ErrorResponseDetail, required)
- `reason` (string, optional, nullable) — Current funding reason when code is still_blocked.
- `topUp` (TopUpHint, optional, nullable) — Set on `credits_exhausted`, and on `still_blocked` with that reason, while agent top-ups are available.

### 404 Not Found Error

The resource or route does not exist (`not_found`).

- `code` (string, required) — Stable machine code. Specific values: `credits_exhausted` (402): Your organization has no available credits. Add credits in Billing to continue.; `spend_limit_reached` (402): A spending limit has been reached. Review the organization's monthly limit and agent caps in Billing.; `billing_unavailable` (503): Spending confirmation is temporarily unavailable. Your progress is saved; retry shortly.; `idempotency_conflict` (409): the idempotency key was already used for a different request, or for a file that was deleted; `concurrent_request` (409): another request is changing the same resource; send the same request again; `agent_disabled` (409): the agent is turned off; turn it on before starting new work; `release_unavailable` (409): the agent has no release that can run; `action_not_pending` (409): the tool call or approval is not waiting for this input: it already has an outcome, its run finished, it is handled by Sikaru, or it does not match a pending request; `still_blocked` (409): funding still prevents this work from resuming; inspect reason; `not_resumable` (409): the run is not waiting for funding or has already resumed; `not_retryable` (409): the run cannot be retried: it did not fail, its failure is not recoverable, or it failed too long ago; `branch_unavailable` (409): the session cannot be branched at that run; `record_invalid` (409): the retained record cannot be read; `state_conflict` (409): the request conflicts with the resource's current state; read it before trying again; `agent_capacity_full` (429): the agent's turn capacity is full; `agent_unavailable` (503): execution is switched off for this agent; `turn_delivery_pending` (503): the message was recorded but has not started; send it again with the same idempotency key; `execution_storage_unavailable` (503): session, file or workspace storage is unavailable right now; `storage_unavailable` (503): the storage behind this resource is unavailable right now; `trajectory_storage_unavailable` (503): retained run records cannot be read right now; `top_up_unavailable` (409): agent credit top-ups are not available for this organization; `top_up_amount_out_of_range` (422): the amount must be whole cents within the per-top-up minimum and maximum; `top_up_blocked` (409): agent top-ups are paused for this organization until support clears them; `release_check_blocked` (409): a release check blocked this version; `detail` is an object with `message`, `publicationId` (the publication Publish Anyway releases) and `results`, one per Grader: `graderId`, `name`, `outcome` (`blocked` or `couldnt_verify`), `flagged` (up to 10 conversation keys flagged only for this version) and `flaggedCount`; `release_check_unverified` (409): a release check couldn't verify this version; `detail` is an object with `message`, `publicationId` (the publication Publish Anyway releases) and `results`, one per Grader: `graderId`, `name`, `outcome` (`blocked` or `couldnt_verify`), `flagged` (up to 10 conversation keys flagged only for this version) and `flaggedCount`; `invalid_grader_file` (422): a Grader file is invalid; `detail` names its path and line; `invalid_grader` (422): the Grader's criteria are invalid; `grader_admin_required` (403): changing a Grader's judge, escalation or release check, or removing a Grader file, needs Grader admin credentials; `grading_off` (409): personal and end-user agents are never graded; `reason_required` (409): turning off or loosening a release check that blocks a release needs a reason, given from the dashboard or the API; `release_check_refused` (409): the release check cannot be turned on: the Grader has no live version; `preset_judge_fixed` (409): built-in Graders keep the decision model and never escalate; `escalation_unavailable` (422): only a Grader judged by the decision model can escalate; `missing_field` (422): a required field for this request is missing; `judge_is_graded_agent` (409): an agent cannot judge its own conversations; `judge_content_private` (409): a personal or end-user agent cannot be a judge; `judge_not_live` (409): the judge agent needs a live version first; `judge_needs_setup` (409): the judge agent must be set up to read a copy of the conversation; `test_unavailable` (503): Grader testing is unavailable right now; `estimate_unavailable` (503): judge pricing is unavailable right now; `regrade_refused` (409): the Grader has no version, or the selected window has no or too many conversations; `regrade_unavailable` (503): history re-scoring is unavailable right now. Otherwise a status default: `bad_request` (400), `unauthenticated` (401), `payment_required` (402), `forbidden` (403), `not_found` (404), `method_not_allowed` (405), `not_acceptable` (406), `request_timeout` (408), `conflict` (409), `gone` (410), `length_required` (411), `precondition_failed` (412), `payload_too_large` (413), `unsupported_media_type` (415), `range_not_satisfiable` (416), `invalid_request` (422), `locked` (423), `precondition_required` (428), `rate_limited` (429), `internal_error` (500), `not_implemented` (501), `bad_gateway` (502), `service_unavailable` (503), `gateway_timeout` (504). `429` and `503` refusals with a specific code carry `Retry-After` in seconds.
- `detail` (ErrorResponseDetail, required)
- `reason` (string, optional, nullable) — Current funding reason when code is still_blocked.
- `topUp` (TopUpHint, optional, nullable) — Set on `credits_exhausted`, and on `still_blocked` with that reason, while agent top-ups are available.

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

## Types

### ImportFile

- `content` (string, required)
- `expectedEtag` (string, required, nullable)
- `path` (string, required)
- `provenance` (string, required)

### ErrorResponseDetail

- string
- map from string to any

### TopUpHint

An agent can add credits itself: create a top-up offer, then pay its URL.

- `cli` (string, required) — CLI command that creates the top-up offer.
- `maxUsd` (string, required)
- `minUsd` (string, required)
- `operation` (string, required) — SDK operation that creates the top-up offer.

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)
- `ctx` (ValidationErrorCtx, optional)
- `input` (any, optional)

### ValidationErrorLocItems

- string
- integer

### ValidationErrorCtx

## Examples

**Request**

```json
{
  "digest": "string",
  "files": [
    {
      "content": "string",
      "expectedEtag": "string",
      "path": "string",
      "provenance": "string"
    }
  ],
  "importId": "string",
  "sourceRevision": "string"
}
```

**Response**

```json
{
  "digest": "string",
  "importId": "string",
  "paths": [
    "string"
  ],
  "sourceRevision": "string",
  "evaluationStatus": "ready"
}
```

**SDK Code**

```python
import requests

url = "https://api.sikaru.ai/v1/projects/project_id/managed-agents/agent_slug/end-users/tenant_id/user_id/imports"

payload = {
    "digest": "string",
    "files": [
        {
            "content": "string",
            "expectedEtag": "string",
            "path": "string",
            "provenance": "string"
        }
    ],
    "importId": "string",
    "sourceRevision": "string"
}
headers = {
    "Authorization": "Bearer <apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.sikaru.ai/v1/projects/project_id/managed-agents/agent_slug/end-users/tenant_id/user_id/imports';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <apiKey>', 'Content-Type': 'application/json'},
  body: '{"digest":"string","files":[{"content":"string","expectedEtag":"string","path":"string","provenance":"string"}],"importId":"string","sourceRevision":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sikaru.ai/v1/projects/project_id/managed-agents/agent_slug/end-users/tenant_id/user_id/imports"

	payload := strings.NewReader("{\n  \"digest\": \"string\",\n  \"files\": [\n    {\n      \"content\": \"string\",\n      \"expectedEtag\": \"string\",\n      \"path\": \"string\",\n      \"provenance\": \"string\"\n    }\n  ],\n  \"importId\": \"string\",\n  \"sourceRevision\": \"string\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.sikaru.ai/v1/projects/project_id/managed-agents/agent_slug/end-users/tenant_id/user_id/imports")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"digest\": \"string\",\n  \"files\": [\n    {\n      \"content\": \"string\",\n      \"expectedEtag\": \"string\",\n      \"path\": \"string\",\n      \"provenance\": \"string\"\n    }\n  ],\n  \"importId\": \"string\",\n  \"sourceRevision\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sikaru.ai/v1/projects/project_id/managed-agents/agent_slug/end-users/tenant_id/user_id/imports")
  .header("Authorization", "Bearer <apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"digest\": \"string\",\n  \"files\": [\n    {\n      \"content\": \"string\",\n      \"expectedEtag\": \"string\",\n      \"path\": \"string\",\n      \"provenance\": \"string\"\n    }\n  ],\n  \"importId\": \"string\",\n  \"sourceRevision\": \"string\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sikaru.ai/v1/projects/project_id/managed-agents/agent_slug/end-users/tenant_id/user_id/imports', [
  'body' => '{
  "digest": "string",
  "files": [
    {
      "content": "string",
      "expectedEtag": "string",
      "path": "string",
      "provenance": "string"
    }
  ],
  "importId": "string",
  "sourceRevision": "string"
}',
  'headers' => [
    'Authorization' => 'Bearer <apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.sikaru.ai/v1/projects/project_id/managed-agents/agent_slug/end-users/tenant_id/user_id/imports");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"digest\": \"string\",\n  \"files\": [\n    {\n      \"content\": \"string\",\n      \"expectedEtag\": \"string\",\n      \"path\": \"string\",\n      \"provenance\": \"string\"\n    }\n  ],\n  \"importId\": \"string\",\n  \"sourceRevision\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "digest": "string",
  "files": [
    [
      "content": "string",
      "expectedEtag": "string",
      "path": "string",
      "provenance": "string"
    ]
  ],
  "importId": "string",
  "sourceRevision": "string"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sikaru.ai/v1/projects/project_id/managed-agents/agent_slug/end-users/tenant_id/user_id/imports")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```