# Apps API

> The REST API behind the SDK, for exported apps and other clients.


Every app's backend is reachable at two base URLs:

| From | Base URL |
|---|---|
| Inside the app (same origin) | `/_ds` |
| Anywhere else | `https://draftship.dev/api/apps/<app-id>` |

CORS is open; authentication is by header, never cookies.

## Authentication

- **App user:** `Authorization: Bearer <token>` from `auth/login` or `auth/register`.
- **Service:** `X-Draftship-Service-Key: <key>` — admin access for server code only.
- **Anonymous:** no header; security rules decide.

## Endpoints

| Method | Path | Body / query |
|---|---|---|
| GET | `/app` | — app id and name |
| POST | `/auth/register` | `{ email, password, full_name? }` |
| POST | `/auth/login` | `{ email, password }` |
| GET / PATCH | `/auth/me` | profile fields on PATCH |
| GET | `/entities/<Name>` | `q` (JSON query), `sort`, `limit`, `skip`, `count=1` |
| POST | `/entities/<Name>` | object or array |
| PATCH | `/entities/<Name>?q=…` | fields to set on all matches |
| DELETE | `/entities/<Name>?q=…` | — deletes all matches |
| GET / PATCH / DELETE | `/entities/<Name>/<id>` | fields on PATCH |
| POST | `/integrations/Core/<Name>` | `InvokeLLM`, `GenerateImage`, `SendEmail` (JSON); `UploadFile` (multipart `file`). Needs a signed-in user or an API key |
| GET | `/files/<name>` | uploaded file |
| GET | `/agents` | — agents and greetings |
| POST / GET | `/agents/<name>/conversations` | create / list (signed-in user's) |
| GET | `/conversations/<id>` | messages |
| POST | `/conversations/<id>/messages` | `{ content }` — returns the agent's reply |
| POST | `/analytics/track` | `{ eventName, properties? }` |
| POST | `/logs` | `{ message, level?, data? }` |

Errors return `{ "error": "…" }` with an HTTP status: 400 invalid input, 401 not signed in, 403 not allowed, 404 not found, 413 too large, 429 limit reached.

## Example

```bash
curl -G "https://draftship.dev/api/apps/<app-id>/entities/Task" \
  --data-urlencode 'q={"done":false}' --data-urlencode 'sort=-created_date'
```