# Coworkies API: start here

Source: https://docs.coworkies.com/api/

> Connect your tools to API v2 with a scoped key, make your first read request and find job and directory integration guides.

Use the Coworkies API to read job listings and directory data or create jobs from your own tools. The base URL is **`https://api.coworkies.com/v2`**. Responses are JSON.

## 1. Get the right API key

For a Pro space, open **Space Admin → API Keys**. Follow [Create and manage space API keys](https://docs.coworkies.com/spaces/api-keys/). For other access needs, request access at [api@coworkies.com](mailto:api@coworkies.com).

Choose the smallest permissions your integration needs. A space key limits supported space-specific data and job operations to that space. It is not a way to gain access to other spaces. City lookups and public content are not all filtered by space; read each endpoint's behavior.

## 2. Make a read request

Set `COWORKIES_API_KEY` in your server's environment or secret store, then run:

```bash
curl --fail-with-body --max-time 30   'https://api.coworkies.com/v2/jobs'   -H "X-API-Key: ${COWORKIES_API_KEY}"
```

Check the HTTP status and `success` field. Job results are in `data.jobs`. An empty list can mean your space has no active jobs.

```json
{
  "success": true,
  "status": 200,
  "data": { "jobs": [], "total": 0 }
}
```

When pagination is enabled by the server, job results include `data.pagination` instead of just a total. See [Jobs API](https://docs.coworkies.com/api/jobs/).

## 3. Choose your integration guide

- [Authentication, responses and errors](https://docs.coworkies.com/api/authentication/): headers, permissions, retries and troubleshooting.
- [Jobs API](https://docs.coworkies.com/api/jobs/): filters, creation, publication status, deduplication and unpublishing.
- [Directory and content endpoints](https://docs.coworkies.com/api/reference/): cities, spaces, blog, events, health and feedback.

## Full developer resources

| Resource | Use |
|---|---|
| [API reference](https://api.coworkies.com/docs/) | Full endpoint examples and request/response fields. |
| [Swagger UI](https://api.coworkies.com/docs/swagger.html) | Interactive reference; write requests can change real data. |
| [OpenAPI specification](https://api.coworkies.com/openapi.yaml) | Import into API tools or generate a client. |
| [Concise LLM reference](https://api.coworkies.com/llms.txt) | Short integration context. |
| [Full LLM reference](https://api.coworkies.com/llms-full.txt) | Detailed integration reference. |

Most data endpoints require a key. Public routes include API information, feedback, newsletter subscription, blog content and Vine feeds. **Health**, **Jobs**, **Cities**, **Spaces** and **Events** require authentication. Keep keys in server-side integrations; do not include them in public frontend code.