# Directory and content API reference

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

> Look up cities and spaces, distinguish city-space metadata from space profiles, and find blog, event, health and feedback endpoints.

All paths below are relative to `https://api.coworkies.com`.

## Cities and spaces

| Endpoint | Permission | Parameters and result |
|---|---|---|
| `GET /v2/cities` | `cities:read` or broad read access | `q`: exact city slug; `search`: partial city name. Returns a `data` array with city identifiers. |
| `GET /v2/spaces` | `spaces:read` or broad read access | `q`: city slug. Returns confirmed spaces; a space key filters to its own space. |
| `GET /v2/city_spaces` | `spaces:read` or broad read access | Returns confirmed space/city metadata, website and LinkedIn URL when available. |

### Resolve a city

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

City fields include `id_city`, `city_name`, `city_slug`, `latitude` and `longitude`. Choose the intended city before using `id_city` in [job creation](https://docs.coworkies.com/api/jobs/).

### Read the space profile data

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

Fields include `space_name`, `space_url` (space slug), `space_address`, `latitude`, `longitude` and `city_name`. `space_url` is not a complete URL. This endpoint does not return the admin membership table or a complete photo gallery.

`city_spaces` additionally includes space and city IDs, website and LinkedIn information. Its coordinates describe the **city**, while `spaces` coordinates describe the **space**. The current city-space directory response is not restricted to the key's own space. Do not assume all endpoints share the same scope filtering.

## Other endpoints

| Endpoint | Authentication | Use |
|---|---|---|
| `GET /v2` | Public | API information and available routes. |
| `GET /v2/blog` | Public | Blog posts: `category`, `tag`, `limit` (default 10, max 50), `offset`; `slug` fetches one post. |
| `GET /v2/events` | Required; event read access | Events. Use the full specification for filters and related endpoints. |
| `GET /v2/health` | Required; broad `read` | Service health response. |
| `POST /v2/feedback` | Public | Submit a required `message`, with optional `email`, `url` and `category`; JSON or form-encoded body. |
| `POST /v2/newsletters/subscribe` | Public | Newsletter subscription; see the full specification for consent and payload requirements. |
| `GET /v2/careers/{slug}` | Public | White-label career board JSON feed for a space (`/v2/careers/brand/{slug}` for a brand, or `/v2/careers?host={hostname}` for custom domains). See [Career portal & custom domain (Beta)](https://docs.coworkies.com/spaces/career-portal/). |
| `GET /v2/vine/jobs`, `/v2/vine/events`, `/v2/vine/blog` | Public | Lightweight feed responses; see the full reference for limits. |

For schemas and further event routes, use the [OpenAPI specification](https://api.coworkies.com/openapi.yaml) and [API reference](https://api.coworkies.com/docs/). Consult [authentication and errors](https://docs.coworkies.com/api/authentication/) before handling failed requests.