> ## 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

> TypeScript interfaces and types

# Types

All TypeScript types exported by `@castari/sdk`.

## Agent

Represents a Castari agent.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
type AgentSourceType = 'git' | 'local';
```

***

## InvocationResponse

Response from invoking an agent.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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).

```typescript theme={null}
interface Secret {
  key: string;
}
```

| Field | Type     | Description                          |
| ----- | -------- | ------------------------------------ |
| `key` | `string` | Secret name (e.g., `OPENAI_API_KEY`) |

***

## CastariClientOptions

Options for creating a client.

```typescript theme={null}
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.

```typescript theme={null}
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:**

```typescript theme={null}
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](https://github.com/castari/cli/blob/main/packages/sdk/src/types.ts).

***

## Importing Types

All types are exported from the main package:

```typescript theme={null}
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

* [CastariClient](/sdk/client) — Client setup
* [Agents API](/sdk/agents) — Agent methods
* [Secrets API](/sdk/secrets) — Secrets methods
* [Auth API](/sdk/auth) — Authentication methods
* [Usage API](/sdk/usage) — Usage statistics
* [Storage API](/sdk/storage) — Cloud bucket storage
* [Mounts API](/sdk/mounts) — Agent mounts
* [Files API](/sdk/files) — Managed file storage