> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baytos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API Overview

> Introduction to the Claro REST API

The Claro REST API provides programmatic access to your prompts, enabling you to integrate Claro into your applications, workflows, and automation tools.

## Base URL

All API requests should be made to:

```
https://api.baytos.ai
```

All endpoints are versioned and prefixed with `/v1`:

```
https://api.baytos.ai/v1/prompts
```

## API Versioning

The API uses URL-based versioning. The current version is `v1`. When we make breaking changes, we'll release a new version (e.g., `v2`) while maintaining support for previous versions.

<Note>
  We maintain backward compatibility for at least 12 months after releasing a new API version.
</Note>

## Available Endpoints

The Claro API provides the following core functionality:

<CardGroup cols={2}>
  <Card title="Get Prompt" icon="sparkles" href="#get-prompt">
    Retrieve a specific prompt by package name
  </Card>

  <Card title="List Prompts" icon="list" href="#list-prompts">
    Browse and paginate through your workspace prompts
  </Card>

  <Card title="Download Files" icon="download" href="#download-files">
    Access context files attached to prompts
  </Card>

  <Card title="Health Check" icon="heart-pulse" href="#health-check">
    Verify API availability and status
  </Card>
</CardGroup>

## Request Format

All API requests should:

* Use HTTPS
* Include proper authentication headers
* Send JSON payloads for POST requests with `Content-Type: application/json`

Example request:

```bash theme={null}
curl https://api.baytos.ai/v1/prompts/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "package_name": "@workspace/my-prompt:v1"
  }'
```

## Response Format

All API responses are returned as JSON with consistent structure:

### Success Response

```json theme={null}
{
  "data": {
    // Response payload
  }
}
```

### Error Response

```json theme={null}
{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": {}  // Optional additional context
  }
}
```

## Common Concepts

### Package Names

Prompts are identified by package names in the format:

```
@namespace/prompt-name:version
```

Examples:

* `@workspace/customer-support:v1` - Published version 1
* `@alice/code-reviewer:v2` - User alice's prompt version 2
* `@team/analytics:latest` - Latest published version

### Pagination

List endpoints use cursor-based pagination:

```json theme={null}
{
  "data": {
    "prompts": [...],
    "cursor": "next_page_token",
    "hasMore": true
  }
}
```

<Tip>
  Always check the `hasMore` field to determine if additional pages exist.
</Tip>

## SDK vs REST API

While you can call the REST API directly, we recommend using our official SDKs for a better developer experience:

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="/sdk/python/installation">
    Type-safe Python client with automatic retries and pagination
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/sdk/typescript/installation">
    Coming soon
  </Card>
</CardGroup>

The SDKs handle:

* Authentication
* Rate limiting and retries
* Error handling
* Type safety
* Response parsing

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn how to authenticate API requests
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/api-reference/rate-limits">
    Understand rate limiting and best practices
  </Card>

  <Card title="Error Handling" icon="shield" href="/api-reference/errors">
    Handle errors gracefully in your application
  </Card>

  <Card title="API Endpoints" icon="code" href="/api-reference/openapi">
    Browse the complete API reference
  </Card>
</CardGroup>

## Need Help?

* **Email:** [support@baytos.ai](mailto:support@baytos.ai)
* **Documentation:** [docs.baytos.ai](https://docs.baytos.ai)
* **Platform:** [claro.baytos.ai](https://claro.baytos.ai)