# API Overview

The Promptly REST API lets you fetch prompts and composers directly over HTTP - no SDK required. Use it from any language or tool that can make HTTP requests.

## Base URL

All API requests use the following base URL:

```
https://api.promptlycms.com
```

## Authentication

Authenticate every request with a Bearer token in the `Authorization` header. Get your API key from the [Promptly CMS dashboard](https://app.promptlycms.com/settings?apiKeys).

```
Authorization: Bearer pk_live_...
```

## Quick start

1. **Get your API key**

   Copy your API key from the [dashboard settings](https://app.promptlycms.com/settings?apiKeys).

2. **Make your first request**

   ```bash
   curl https://api.promptlycms.com/prompts/your-prompt-id \
     -H "Authorization: Bearer pk_live_..."
   ```
   ```typescript
   const response = await fetch(
     'https://api.promptlycms.com/prompts/your-prompt-id',
     {
       headers: {
         Authorization: 'Bearer pk_live_...',
       },
     },
   );
   const prompt = await response.json();
   ```
3. **Use the response**

   The API returns JSON with the prompt content, model configuration, and template variables:

   ```json
   {
     "promptId": "your-prompt-id",
     "promptName": "My Prompt",
     "version": "1.0.0",
     "systemMessage": "You are a helpful assistant.",
     "userMessage": "Help ${name} with ${task}.",
     "config": {
       "model": "claude-sonnet-4.6",
       "temperature": 0.7,
       "schema": [],
       "inputData": null,
       "inputDataRootName": null
     }
   }
   ```

## Composers

In addition to individual prompts, the API supports **composers** -- multi-prompt workflows that combine static content with prompt segments. Fetch composers via `GET /composers` and `GET /composers/:composerId`. See the [Endpoints](https://docs.promptlycms.com/api/endpoints/) reference for full details.

## CORS

The API supports CORS for all origins. Only `GET` and `OPTIONS` methods are allowed - the API is read-only.

## Performance

API responses typically return in **50-80ms**, making Promptly fast enough for speed-critical applications. This means you can fetch prompts at request time rather than only at startup - your users won't notice the overhead.

## REST API vs SDK

| | REST API | TypeScript SDK |
|---|---|---|
| **Language** | Any | TypeScript/JavaScript |
| **Type safety** | Manual | Automatic (with codegen) |
| **Model resolution** | Manual | Automatic (AI SDK models) |
| **Template interpolation** | Manual string replacement | Built-in `userMessage()` function |
| **Best for** | Non-TypeScript apps, debugging, scripting | TypeScript apps with AI SDK |

**Tip:** If you're building a TypeScript application, the [SDK](https://docs.promptlycms.com/getting-started/quick-start/) handles authentication, model resolution, and template interpolation automatically.

## Next steps

- [Endpoints](https://docs.promptlycms.com/api/endpoints/) - full reference for all API endpoints
- [Rate Limits](https://docs.promptlycms.com/api/rate-limits/) - usage quotas and rate limit headers
- [Errors](https://docs.promptlycms.com/api/errors/) - error codes and troubleshooting