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'
  | 'pending'
  | 'deploying'
  | 'active'
  | 'stopped'
  | 'failed';
StatusDescription
draftCreated but not configured
pendingConfigured but never deployed
deployingDeployment in progress
activeRunning and ready for invocations
stoppedManually stopped
failedDeployment 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 {
  status: number;
  code?: string;
  detail?: string;
}
FieldTypeDescription
messagestringHuman-readable error message
statusnumberHTTP status code
codestring?Error code (e.g., agent_not_found)
detailstring?Additional details
Example:
try {
  await client.agents.get('nonexistent');
} catch (error) {
  if (error instanceof CastariError) {
    console.log(error.status);  // 404
    console.log(error.message); // "Agent not found"
  }
}

Importing Types

All types are exported from the main package:
import {
  CastariClient,
  CastariClientOptions,
  CastariError,
  Agent,
  AgentStatus,
  AgentSourceType,
  InvocationResponse,
  InvokeOptions,
  CreateAgentOptions,
  UploadResponse,
  Secret,
} from '@castari/sdk';

See Also