Documentation Index
Fetch the complete documentation index at: https://docs.castari.com/llms.txt
Use this file to discover all available pages before exploring further.
Types
All TypeScript types exported by @castari/sdk.
Agent
Represents a Castari agent.
interface Agent {
id: string;
user_id: string;
name: string;
slug: string;
description?: string | null;
source_type: AgentSourceType;
git_repo_url?: string | null;
git_branch: string;
source_hash?: string | null;
default_model: string;
max_turns: number;
timeout_seconds: number;
status: AgentStatus;
status_message?: string | null;
sandbox_id?: string | null;
created_at: string;
updated_at: string;
}
| Field | Type | Description |
|---|
id | string | Unique identifier |
name | string | Display name |
slug | string | URL-safe identifier |
status | AgentStatus | Current status |
source_type | AgentSourceType | 'git' or 'local' |
git_repo_url | string? | Source repository URL |
sandbox_id | string? | Active sandbox ID (when deployed) |
created_at | string | ISO 8601 timestamp |
updated_at | string | ISO 8601 timestamp |
AgentStatus
Possible agent statuses.
type AgentStatus =
| 'draft'
| 'deploying'
| 'active'
| 'stopped'
| 'error';
| Status | Description |
|---|
draft | Created but not yet deployed |
deploying | Deployment in progress |
active | Running and ready for invocations |
stopped | Manually stopped |
error | Deployment or runtime error |
AgentSourceType
Source type for agent code.
type AgentSourceType = 'git' | 'local';
InvocationResponse
Response from invoking an agent.
interface InvocationResponse {
invocation_id: string;
session_id: string;
sandbox_id?: string | null;
response_content: string;
input_tokens: number;
output_tokens: number;
total_cost_usd: number | string;
duration_ms: number;
status: 'completed' | 'failed';
}
| Field | Type | Description |
|---|
invocation_id | string | Unique identifier (e.g., inv_abc123) |
session_id | string | Session ID for the invocation |
response_content | string | Agent’s response text |
input_tokens | number | Tokens in the prompt |
output_tokens | number | Tokens in the response |
total_cost_usd | number | string | Total cost in USD |
duration_ms | number | Execution time in milliseconds |
status | string | 'completed' or 'failed' |
InvokeOptions
Options for invoking an agent.
interface InvokeOptions {
prompt: string;
sessionId?: string;
}
| Field | Type | Required | Description |
|---|
prompt | string | Yes | The prompt to send |
sessionId | string | No | Session ID for conversation continuity |
CreateAgentOptions
Options for creating an agent.
interface CreateAgentOptions {
name: string;
slug?: string;
description?: string;
sourceType?: AgentSourceType;
gitRepoUrl?: string;
}
| Field | Type | Required | Description |
|---|
name | string | Yes | Display name for the agent |
slug | string | No | URL-safe identifier (auto-generated if omitted) |
description | string | No | Agent description |
sourceType | AgentSourceType | No | 'git' (default) or 'local' |
gitRepoUrl | string | No | Git repository URL |
UploadResponse
Response from uploading code.
interface UploadResponse {
agent_id: string;
source_hash: string;
status: AgentStatus;
sandbox_id?: string | null;
message: string;
}
Secret
Represents a secret (metadata only — values are never returned).
interface Secret {
key: string;
}
| Field | Type | Description |
|---|
key | string | Secret name (e.g., OPENAI_API_KEY) |
CastariClientOptions
Options for creating a client.
interface CastariClientOptions {
apiKey?: string;
token?: string;
baseUrl?: string;
}
| Field | Type | Description |
|---|
apiKey | string | API key (starts with cast_) |
token | string | OAuth token |
baseUrl | string | API base URL (default: https://api.castari.com) |
CastariError
Error thrown by SDK operations.
class CastariError extends Error {
statusCode: number;
code?: string;
}
| Field | Type | Description |
|---|
message | string | Human-readable error message |
statusCode | number | HTTP status code |
code | string? | Error code (e.g., agent_not_found) |
Example:
try {
await client.agents.get('nonexistent');
} catch (error) {
if (error instanceof CastariError) {
console.log(error.statusCode); // 404
console.log(error.message); // "Agent not found"
}
}
Storage v2 Types
The SDK includes types for managed file storage (Storage v2):
ManagedFile — File metadata (id, filename, size, scope, tags, status)
FileUploadResponse — Upload result
ManagedFileList — Paginated file list with metadata
StorageUsage — Quota information (total files, bytes, limits)
PresignedUpload — Presigned URL for large file uploads
AgentFile — File attached to an agent
AgentFileList — List of agent-attached files
See the full type definitions in types.ts.
Importing Types
All types are exported from the main package:
import {
CastariClient,
CastariClientOptions,
CastariError,
Agent,
AgentStatus,
AgentSourceType,
InvocationResponse,
InvokeOptions,
CreateAgentOptions,
UpdateAgentOptions,
UploadResponse,
Secret,
User,
ApiKeyInfo,
ApiKeyCreateResponse,
UsageSummary,
DailyUsage,
Bucket,
Mount,
ManagedFile,
StorageUsage,
} from '@castari/sdk';
See Also