# REST API

> The Solk CRM JSON API — the same endpoints the mobile app uses, with the same permission rules and the same business rules.

The Solk REST API lets you read and modify the companies, people, opportunities, actions, calendar, fair leads, and email threads in your installation. Solk's iOS / Android app uses this same API, so the endpoints are shaped around a real sales rep's screens: a single request returns everything a screen needs.

## Basics

| | |
|---|---|
| Base URL | `https://<company>.solk.app/api/v1` |
| Format | JSON (`Content-Type: application/json`); most write endpoints also accept a form body |
| Authentication | `Authorization: Bearer <token>` — [API key, OAuth, or mobile session](/rest-api/authentication) |
| Character set | UTF-8; Turkish characters are returned as is |
| Dates | `YYYY-MM-DD`; date-times `YYYY-MM-DDTHH:MM:SS` (the installation's local time) |
| Rate limit | 300 requests per minute per token — [Rate limits](/rest-api/rate-limits) |
| Specification | [`/openapi.json`](/openapi.json) (OpenAPI 3.1) |

## Response envelope

Every response is a JSON object with an `ok` field:

```json
{ "ok": true, "customer": { "id": 31, "name": "Kuzey Plastik Sanayi", "…": "…" } }
```

Error responses include an HTTP status code, a machine-readable `error` code, and a Turkish `message` you can show to users; some errors carry extra fields (`similar`, `gate_problems`…):

```json
{ "ok": false, "error": "gate", "message": "Viable'a geçmek için: BANT kriterleri 4/4 sağlanmalı …", "gate_problems": ["…"] }
```

All codes: [Errors](/rest-api/errors).

## Resources

:::cards
- [Authentication](/rest-api/auth/me) key | Who you are, enabled modules, installation constants.
- [Workspace](/rest-api/workspace/today) layout | Today, dashboard, search, notifications.
- [Companies](/rest-api/companies/list) building | List, get, create, update, postpone.
- [People](/rest-api/people/list) user | Contacts at your companies.
- [Opportunities](/rest-api/deals/list) target | Stages, BANT, steps, revival.
- [Activities](/rest-api/activities/log) phone | Log calls and visits (Quick Entry).
- [Actions and tasks](/rest-api/actions/list) check | Complete, postpone, chain.
- [Calendar](/rest-api/calendar/list) calendar | Meetings and derived entries.
- [Fairs and leads](/rest-api/fairs/list) flag | Booth records.
- [Email](/rest-api/email/threads-list) mail | Threads, linking, sending.
- [Ask](/rest-api/ask/ask) spark | Ask questions about your CRM data in natural language.
- [SCIM 2.0](/rest-api/scim) shield | User management.
:::

## Versioning

The API path `/api/v1` is fixed. New fields and endpoints are **additive**; existing fields are never removed and their meaning never changes. Your client should ignore fields it doesn't recognize. When a breaking change is necessary, a new path (`/api/v2`) is introduced and announced in advance in the [changelog](/changelog).

## Methods for write endpoints

Update endpoints accept `PATCH`, `PUT`, and `POST` interchangeably (for older HTTP clients and the mobile app). Updates are **partial**: only the fields you send change (the one exception: for a [fair lead](/rest-api/fairs/leads-update), sending `company` rewrites all form fields). To clear a text field, send an empty string (`""`); a field sent as `null` is ignored (left unchanged).

Send boolean fields as JSON `true` / `false`. In a form body (`application/x-www-form-urlencoded`), send `1` for true and leave the field empty for false.