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

# Secrets API

> Manage agent secrets programmatically

# Secrets API

The Secrets API lets you manage environment variables for your agents.

Access via `client.secrets`:

```typescript theme={null}
const client = new CastariClient({ apiKey: '...' });
const secrets = client.secrets;
```

## Methods

### list(slug)

List all secrets for an agent.

```typescript theme={null}
const secrets = await client.secrets.list(slug);
```

**Parameters:**

| Name   | Type     | Description      |
| ------ | -------- | ---------------- |
| `slug` | `string` | The agent's slug |

**Returns:** `Promise<Secret[]>`

**Example:**

```typescript theme={null}
const secrets = await client.secrets.list('my-agent');

for (const secret of secrets) {
  console.log(`${secret.key} - created ${secret.created_at}`);
}
```

<Note>
  Secret values are never returned by the API. Only keys and metadata are included.
</Note>

***

### set(slug, key, value)

Set a secret for an agent.

```typescript theme={null}
await client.secrets.set(slug, key, value);
```

**Parameters:**

| Name    | Type     | Description                          |
| ------- | -------- | ------------------------------------ |
| `slug`  | `string` | The agent's slug                     |
| `key`   | `string` | Secret name (e.g., `OPENAI_API_KEY`) |
| `value` | `string` | Secret value                         |

**Returns:** `Promise<void>`

**Example:**

```typescript theme={null}
await client.secrets.set(
  'my-agent',
  'OPENAI_API_KEY',
  'sk-abc123...'
);
```

<Warning>
  Setting a secret with an existing key will overwrite the previous value.
</Warning>

***

### delete(slug, key)

Delete a secret from an agent.

```typescript theme={null}
await client.secrets.delete(slug, key);
```

**Parameters:**

| Name   | Type     | Description          |
| ------ | -------- | -------------------- |
| `slug` | `string` | The agent's slug     |
| `key`  | `string` | Secret key to delete |

**Returns:** `Promise<void>`

**Example:**

```typescript theme={null}
await client.secrets.delete('my-agent', 'OLD_API_KEY');
```

## Full Example

```typescript theme={null}
import { CastariClient } from '@castari/sdk';

async function setupAgentSecrets() {
  const client = new CastariClient({
    apiKey: process.env.CASTARI_API_KEY,
  });

  const agentSlug = 'my-agent';

  // Set multiple secrets
  await client.secrets.set(agentSlug, 'OPENAI_API_KEY', process.env.OPENAI_API_KEY);
  await client.secrets.set(agentSlug, 'DATABASE_URL', process.env.DATABASE_URL);

  // List to verify
  const secrets = await client.secrets.list(agentSlug);
  console.log(`Agent has ${secrets.length} secrets configured`);

  // Clean up old secret
  await client.secrets.delete(agentSlug, 'DEPRECATED_KEY');
}

setupAgentSecrets();
```

## CI/CD Example

Setting secrets in a GitHub Actions workflow:

```yaml theme={null}
- name: Configure agent secrets
  env:
    CASTARI_API_KEY: ${{ secrets.CASTARI_API_KEY }}
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  run: |
    npx ts-node scripts/setup-secrets.ts
```

```typescript theme={null}
// scripts/setup-secrets.ts
import { CastariClient } from '@castari/sdk';

const client = new CastariClient({
  apiKey: process.env.CASTARI_API_KEY,
});

await client.secrets.set('my-agent', 'OPENAI_API_KEY', process.env.OPENAI_API_KEY);
```

## See Also

* [Agents API](/sdk/agents) — Manage agents
* [cast secrets](/cli/secrets) — CLI equivalent
* [Secrets Concept](/concepts/secrets) — How secrets work