dow-prod-tracker/docs/EXTERNAL_API.md

L'Oréal Studio Tracker — External API (v1)

Server-to-server API for creating projects and deliverables from external systems (e.g. OMG, brief intake forms, integration scripts).

Base URL: https://optical-dev.oliver.solutions/loreal-prod-tracker/api/v1

Auth

Send the shared API key on every request:

x-api-key: <API_KEY>

The key matches process.env.API_KEY on the server. Requests with a missing or wrong key get 401 Unauthorized.

Optionally specify which organization the request applies to:

x-org-id: <organization-id>

If omitted, requests apply to the first organization in the database (useful in single-org deployments).

Idempotency

POST endpoints honour Idempotency-Key. A retried request with the same key + same payload returns the cached response without re-executing:

idempotency-key: 7f3c8e2a-...-deterministic-uuid

The same key with a different payload returns 409 Conflict. Records expire after 24 hours.

Endpoints

GET /api/v1/projects

List all projects visible to the caller. Returns the same shape as the in-app /api/projects.

POST /api/v1/projects

Create a project. If pipelineTemplateId is omitted, the org's default pipeline template is auto-applied. Body matches createProjectSchema (see src/lib/validators/project.ts).

Required fields:

• projectCode (string, unique per org)
• name (string)

Recommended fields:

• omgJobNumber (string) — enables Box-folder matching downstream
• clientTeamId (string) — drives team visibility
• requestorUserId (string) — project owner
• priority (LOW | MEDIUM | HIGH | URGENT)
• status (PIPELINE | ACTIVE | …)
• startDate, dueDate (ISO 8601)

Returns 201 + the created project.

curl -X POST \
  -H "x-api-key: $API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
        "projectCode": "API-001",
        "name": "Test integration project",
        "omgJobNumber": "12345",
        "priority": "MEDIUM"
      }' \
  https://optical-dev.oliver.solutions/loreal-prod-tracker/api/v1/projects

GET /api/v1/projects/{projectId}

Read-back. Same shape as in-app /api/projects/{id} — includes deliverables, stages, attachments, requestor user, client team.

POST /api/v1/projects/{projectId}/deliverables

Create a deliverable on the given project. Pipeline stages auto-applied from the project's template (Deliverable.pipelineTemplate cascades to DeliverableStage rows). Body matches createDeliverableSchema.

Required fields:

• name (string)

Common fields:

• priority, dueDate, notes, externalId (idempotency for upstream webhook callers — distinct from the Idempotency-Key header)

Returns 201 + the created deliverable with its stage chain populated.

curl -X POST \
  -H "x-api-key: $API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
        "name": "Hero banner",
        "priority": "HIGH",
        "dueDate": "2026-06-30T12:00:00Z"
      }' \
  https://optical-dev.oliver.solutions/loreal-prod-tracker/api/v1/projects/$PROJECT_ID/deliverables

Error shapes

{ "error": "Project code \"X\" already exists" }

All errors return JSON with an error string. Status codes:

• 400 — validation error (zod issues joined into one message)
• 401 — missing/wrong API key
• 404 — project not visible (RBAC) or not found
• 409 — Idempotency-Key reused with a different payload
• 500 — server error (check server logs)

What's NOT here

• Update/delete endpoints — out of scope for v1. External callers create; in-app users update.
• Deliverable read-back — GET /api/v1/projects/{id} includes deliverables in its response. A dedicated deliverable read endpoint can be added if external callers need it.
• Bulk endpoints — call POST per project/deliverable.

Internal notes

• Auth path: src/middleware.ts short-circuits API-key requests before the session check. src/lib/api-utils.ts getAuthSession() resolves the key into a synthetic ADMIN session for the chosen org.
• Idempotency: src/lib/api/idempotency.ts + IdempotencyRecord prisma model. 24-hour TTL — sweep via cron (see scripts/).
• Default pipeline fallback: src/lib/services/project-service.ts createProject() — looks up the org's PipelineTemplate.isDefault if no pipelineTemplateId is supplied.