Skip to main content

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;
}
FieldTypeDescription
idstringUnique identifier
namestringDisplay name
slugstringURL-safe identifier
statusAgentStatusCurrent status
source_typeAgentSourceType'git' or 'local'
git_repo_urlstring?Source repository URL
sandbox_idstring?Active sandbox ID (when deployed)
created_atstringISO 8601 timestamp
updated_atstringISO 8601 timestamp

AgentStatus

Possible agent statuses.
type AgentStatus =
  | 'draft'
  | 'deploying'
  | 'active'
  | 'stopped'
  | 'error';
StatusDescription
draftCreated but not yet deployed
deployingDeployment in progress
activeRunning and ready for invocations
stoppedManually stopped
errorDeployment 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';
}
FieldTypeDescription
invocation_idstringUnique identifier (e.g., inv_abc123)
session_idstringSession ID for the invocation
response_contentstringAgent’s response text
input_tokensnumberTokens in the prompt
output_tokensnumberTokens in the response
total_cost_usdnumber | stringTotal cost in USD
duration_msnumberExecution time in milliseconds
statusstring'completed' or 'failed'

InvokeOptions

Options for invoking an agent.
interface InvokeOptions {
  prompt: string;
  sessionId?: string;
}
FieldTypeRequiredDescription
promptstringYesThe prompt to send
sessionIdstringNoSession ID for conversation continuity

CreateAgentOptions

Options for creating an agent.
interface CreateAgentOptions {
  name: string;
  slug?: string;
  description?: string;
  sourceType?: AgentSourceType;
  gitRepoUrl?: string;
}
FieldTypeRequiredDescription
namestringYesDisplay name for the agent
slugstringNoURL-safe identifier (auto-generated if omitted)
descriptionstringNoAgent description
sourceTypeAgentSourceTypeNo'git' (default) or 'local'
gitRepoUrlstringNoGit 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;
}
FieldTypeDescription
keystringSecret name (e.g., OPENAI_API_KEY)

CastariClientOptions

Options for creating a client.
interface CastariClientOptions {
  apiKey?: string;
  token?: string;
  baseUrl?: string;
}
FieldTypeDescription
apiKeystringAPI key (starts with cast_)
tokenstringOAuth token
baseUrlstringAPI base URL (default: https://api.castari.com)

CastariError

Error thrown by SDK operations.
class CastariError extends Error {
  statusCode: number;
  code?: string;
}
FieldTypeDescription
messagestringHuman-readable error message
statusCodenumberHTTP status code
codestring?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