> For the complete documentation index, see [llms.txt](https://docs.adaptria.locaria.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.adaptria.locaria.com/internal-api/quickstart-connector.md).

# Quickstart

This guide shows how an external system (for example, a translation management platform) can create an Adaptria project programmatically. The flow is: gather the catalogue IDs your project references, upload any source assets, then submit the project with `POST /api/public/v1/projects`.

All examples use the production base URL `https://api.adaptria.locaria.com`. Swap in another [environment](/internal-api/environments.md) as needed, and build against staging or test first.

## 1. Authenticate

Send your connector key in the `Api-key` header on every request:

```bash
curl https://api.adaptria.locaria.com/api/public/v1/projects \
  -H "Api-key: lla_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## 2. Gather catalogue IDs

A project references entities by ID. Resolve them up front from the reference endpoints:

| Need                     | Endpoint                                   |
| ------------------------ | ------------------------------------------ |
| Global service catalogue | `GET /api/public/v1/services`              |
| Per-client services      | `GET /api/public/v1/client/services`       |
| Languages                | `GET /api/public/v1/client/languages`      |
| Target markets           | `GET /api/public/v1/client/target-markets` |
| Companies                | `GET /api/public/v1/client/companies`      |
| Project contacts         | `GET /api/public/v1/clients/{id}/users`    |

Fetch the client users for the target company, present them to the end user, and pass back whatever they choose as the project's `clientUsers`.

## 3. Upload source assets

If your project ships source content, upload each file and keep the returned `fileId`:

```bash
curl -X POST https://api.adaptria.locaria.com/api/public/v1/files/upload/presigned-url \
  -H "Api-key: lla_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@/path/to/source-content.zip"
```

## 4. Create the project

Submit the project with an `Idempotency-Key` so retries are safe. Carry your own stable identifier in `externalId` (for example, the upstream order or ticket ID).

```bash
curl -X POST https://api.adaptria.locaria.com/api/public/v1/projects \
  -H "Api-key: lla_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "crowdin-order-12345",
    "companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "projectName": "Q4 Website Localisation",
    "projectDescription": "Localise the marketing site into French, German and Japanese.",
    "projectDueDate": "2026-06-30T17:00:00Z",
    "sourceLanguage": "en",
    "targetLanguages": ["fr", "de", "ja"],
    "clientUsers": ["jane.doe@example.com"]
  }'
```

The project lands in **Draft** status with a generated `projectNumber` for a project manager to enrich and action. See [Idempotency-Key conventions](/internal-api/idempotency.md) for the full retry semantics.

## 5. Track the project

Once created, follow the project and retrieve its outputs:

* `GET /api/public/v1/projects/{id}`: full project details and status.
* `GET /api/public/v1/projects/{id}/deliverables`: completed delivery files.

## Where to go next

* See the [API Reference](/internal-api/reference.md) for the complete catalogue of endpoints and their parameters.