SDK configuration and async usage

Use the authenticated client setup from Quickstart. The examples below read an existing run: set SIKARU_PROJECT_ID and SIKARU_RUN_ID to its identifiers.

Make async requests in Python

Use AsyncSikaruApi in an async application. Supply an async HTTP client when you need explicit connection cleanup or transport configuration.

import asyncio
import os
import httpx
from sikaru_api import AsyncSikaruApi
async def main():
    async with httpx.AsyncClient(timeout=20) as transport:
        client = AsyncSikaruApi(
            api_key=os.environ["SIKARU_API_KEY"],
            base_url=os.environ["SIKARU_BASE_URL"],
            httpx_client=transport,
            timeout=20,
            max_retries=0,
        )
        run = await client.runs.get(
            os.environ["SIKARU_PROJECT_ID"], os.environ["SIKARU_RUN_ID"],
            request_options={"timeout": 10},
        )
        print(run.status)
asyncio.run(main())

The synchronous SikaruApi accepts the same timeout and retry options, with httpx.Client for its transport. Python timeouts are in seconds. Per-request timeout and max_retries override client defaults.

Handle errors and raw responses

from sikaru_api.core.api_error import ApiError
try:
    response = client.runs.with_raw_response.get(project, run_id)
    print(response.status_code)
    print(response.data.status)
except ApiError as error:
    print("Sikaru request failed:", error.status_code)

Here client is a synchronous client and run_id is an existing run ID. Raw responses also expose headers. Handle network and timeout errors from the HTTP transport separately. Log only the response fields you need for diagnosis: bodies and headers can contain customer data.

Error responses have the body {"detail": ..., "code": ...}. 422 validation errors list invalid fields in detail instead.

• code is specific where one applies, such as idempotency_conflict. Otherwise it is a status default such as not_found.
• In Python, read error.body.code and error.headers["retry-after"].
• A 429 or 503 refusal with a code includes Retry-After in seconds.
• A failed run is not an error response. Read error.code and error.recoverable on the run itself. See Runs and tool requests.

Set TypeScript request options

import { SikaruApi } from "@sikaru/sdk";
const client = new SikaruApi({
  apiKey: process.env.SIKARU_API_KEY!,
  baseUrl: process.env.SIKARU_BASE_URL!,
  timeoutInSeconds: 20,
  maxRetries: 0,
});
const run = await client.runs.get(
  process.env.SIKARU_PROJECT_ID!, process.env.SIKARU_RUN_ID!,
  { timeoutInSeconds: 10 },
);
console.log(run.status);

Keep the key in server-side code. Use your language client’s reference for error types and request-option names. They are not identical across languages.

Page through results and events

Pagination is endpoint-specific:

Read each response envelope and pass its continuation cursor to the same endpoint, keeping the same filters. Do not assume these clients automatically read every page.

For run events, persist the cursor and pass it as after on the next JSON page. Deduplicate by event identity if a page arrives again. runs.events returns a JSON page. For the dedicated SSE iterator, use runs.stream_events in Python or runs.streamEvents in TypeScript. See Runs and tool requests.

Poll self-hosted compute with JSON

Each role uses ordinary generated HTTP methods, without requiring SSE support:

An executor can inspect its scoped work page:

from sikaru_api import SikaruApi
executor = SikaruApi(base_url=api_url, api_key=attachment_token)
page = executor.compute_operations.poll(project_id, attachment_id, wait_seconds=0)
# Empty operations are not completion; inspect the execution summary separately.
print(page.execution_phase)

The native executor owns readiness, monotonic lease deadlines, process supervision, fsynced intents, and immutable receipt submission. Use sikaru compute serve in your sandbox unless you implement that entire executor contract. Never pass a controller credential to the sandbox.

See Local compute for bootstrap fields, approvals, file boundaries, and recovery.

Next steps