BrightshoalDocsOpen console
    MenuProjects

    API reference

    Projects

    Projects group assistants, numbers and keys inside an organization.

    List projects

    GET/api/projects

    Projects in the organization. A project-scoped key sees only its own project.

    Secret API key. How it works

    Returns

    200 OK

    Response attributes

    • dataarray of Projectrequired

      6 attributes

      • idstringrequired

      • org_idstringrequired

      • namestringrequired

      • webhook_secret_setbooleanrequired

        Whether an agent webhook secret is configured. The secret itself is write-only and never returned.

      • created_atstringISO 8601 timestamp

      • updated_atstringISO 8601 timestamp

    • 401 Missing, malformed, unknown or revoked API key (unauthorized)
    • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
    GET /api/projects
    curl "https://api.myleadsfactory.tech/api/projects" \
  -H "Authorization: Bearer $MLF_API_KEY"
    Response 200
    {
  "data": [
    {
      "id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "name": "Front desk",
      "webhook_secret_set": true,
      "created_at": "2026-10-28T09:30:00.000Z",
      "updated_at": "2026-10-28T09:30:00.000Z"
    }
  ]
}

    Create a project

    POST/api/projects

    A new project to hold assistants, numbers, keys and webhooks. Needs an org-wide key: a project-scoped key gets 403 invalid_request ("A project-scoped key cannot create projects.").

    Secret API key, not read-only, org-wide (not pinned to a project). How it works

    Request body

    • namestringrequirednot empty

    Returns

    201 OK

    Response attributes

    • dataProjectrequired

      6 attributes

      • idstringrequired

      • org_idstringrequired

      • namestringrequired

      • webhook_secret_setbooleanrequired

        Whether an agent webhook secret is configured. The secret itself is write-only and never returned.

      • created_atstringISO 8601 timestamp

      • updated_atstringISO 8601 timestamp

    • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
    • 401 Missing, malformed, unknown or revoked API key (unauthorized)
    • 403 Refused, for example a read-only key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
    • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
    POST /api/projects
    curl -X POST "https://api.myleadsfactory.tech/api/projects" \
  -H "Authorization: Bearer $MLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Front desk"
}'
    Response 201
    {
  "data": {
    "id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "webhook_secret_set": true,
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

    Get a project

    GET/api/projects/{id}

    One project, with whether its agent webhook secret is set.

    Secret API key. How it works

    Path parameters

    • idstringrequired

      Project id, proj_....

    Returns

    200 OK

    Response attributes

    • dataProjectrequired

      6 attributes

      • idstringrequired

      • org_idstringrequired

      • namestringrequired

      • webhook_secret_setbooleanrequired

        Whether an agent webhook secret is configured. The secret itself is write-only and never returned.

      • created_atstringISO 8601 timestamp

      • updated_atstringISO 8601 timestamp

    • 401 Missing, malformed, unknown or revoked API key (unauthorized)
    • 404 Not found, or outside what the key can see
    • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
    GET /api/projects/{id}
    curl "https://api.myleadsfactory.tech/api/projects/PROJECT_ID" \
  -H "Authorization: Bearer $MLF_API_KEY"
    Response 200
    {
  "data": {
    "id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "webhook_secret_set": true,
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

    Update a project

    PATCH/api/projects/{id}

    webhook_secret is write-only: it is never returned by any endpoint, only reflected as webhook_secret_set. Send null to clear it; the project's next call mints a new one.

    Secret API key, not read-only. How it works

    Path parameters

    • idstringrequired

      Project id, proj_....

    Request body

    • namestringnot empty

    • webhook_secretstring | nullat least 16 characters

      HMAC key the agent signs this project's lifecycle webhooks with. Write-only; null clears it, and the project's next call mints a new one.

    Returns

    200 OK

    Response attributes

    • dataProjectrequired

      6 attributes

      • idstringrequired

      • org_idstringrequired

      • namestringrequired

      • webhook_secret_setbooleanrequired

        Whether an agent webhook secret is configured. The secret itself is write-only and never returned.

      • created_atstringISO 8601 timestamp

      • updated_atstringISO 8601 timestamp

    • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
    • 401 Missing, malformed, unknown or revoked API key (unauthorized)
    • 403 Refused, for example a read-only key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
    • 404 Not found, or outside what the key can see
    • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
    PATCH /api/projects/{id}
    curl -X PATCH "https://api.myleadsfactory.tech/api/projects/PROJECT_ID" \
  -H "Authorization: Bearer $MLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Travel UK"
}'
    Response 200
    {
  "data": {
    "id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "webhook_secret_set": true,
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}