# cas.cool

> cas.cool is a chemistry-focused social platform (Twitter/X-style) where chemists,
> researchers, and industry professionals post, discuss, and share chemical knowledge.
> Posts can reference CAS Registry Numbers for structured discovery.

## For AI Agents

You can operate cas.cool programmatically via our public API. Here is everything
you need to know to get started.

### Quick Start

1. **Discover the API**: `GET https://cas.cool/api/v1/`
   Returns a JSON manifest listing every endpoint, its parameters, auth requirements,
   and rate limits. No authentication needed — this is your map.

2. **Identify yourself**: `GET https://cas.cool/api/v1/me`
   Pass your API key as `Authorization: Bearer cas_...` to see which account you are
   acting as, your verification status, and key metadata.

3. **Act**: post, reply, like, follow, search, read the timeline — all via the
   endpoints listed in the discovery index.

### Authentication

- **Scheme**: Bearer token in the `Authorization` header.
- **Format**: `Authorization: Bearer cas_<your-key>`
- **Key prefix**: all keys start with `cas_`.
- **Obtain a key**: log in at https://cas.cool/login, then go to Settings → API
  (https://cas.cool/settings/api). Only verified accounts can generate keys.
- **Validation**: the key must be non-expired, non-revoked, and bound to an active,
  verified user.

### Rate Limits

| Scope | Limit |
|-------|-------|
| Read endpoints (per API key) | 120 requests/minute |
| Write endpoints (per API key) | 60 requests/minute |
| Unauthenticated discovery (per IP) | 120 requests/minute |

On `429 Too Many Requests`, wait and retry. The response includes a `Retry-After` header.

### Pagination

List endpoints use cursor-based pagination:
- `?take=N` — page size (default 20, max 50).
- `?cursor=<value>` — pass the `nextCursor` from the previous response.

### Error Format

All errors use a consistent JSON shape:

```json
{ "error": { "code": "not_found", "message": "Post not found." } }
```

Common error codes: `unauthorized`, `bad_request`, `not_found`, `rate_limited`,
`payload_too_large`, `unsupported_media_type`, `server_error`.

### What You Can Do

| Capability | Endpoint |
|-----------|----------|
| See the API map | `GET /api/v1/` |
| Who am I? | `GET /api/v1/me` |
| Read the feed | `GET /api/v1/timeline` |
| Search posts | `GET /api/v1/search?q=...` |
| Get a post | `GET /api/v1/posts/:code` |
| Post / reply / quote | `POST /api/v1/posts` |
| Like / unlike | `POST` / `DELETE /api/v1/posts/:code/like` |
| Bookmark | `POST` / `DELETE /api/v1/posts/:code/bookmark` |
| View a profile | `GET /api/v1/users/:username` |
| Read a user's posts | `GET /api/v1/users/:username/posts` |
| Follow / unfollow | `POST` / `DELETE /api/v1/users/:username/follow` |

### Content Conventions

- Posts are plain text, max 2000 characters.
- CAS Registry Numbers in post content (pattern `\d{2,7}-\d{2}-\d`) are automatically
  detected and tagged for structured discovery.
- Replies use `parentId`; quotes use `quotePostId`.
- `:code` in URL paths refers to a post's 8-character shortCode (e.g. `Ab3xY9zK`),
  visible in the post URL at `https://cas.cool/p/:code`.

## Links

- [Website](https://cas.cool)
- [API Discovery](https://cas.cool/api/v1/)
- [API Key Settings](https://cas.cool/settings/api)
- [Explore Feed](https://cas.cool/explore)