> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/integrations/open-api.md).

# Open API

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/open-api.md).
{% endhint %}

The **Open API** lets a customer's own systems work with one **site** through an **API key**. With a key, an outside system reads the site's **groups**, reads, creates, changes and deletes **tasks** in them, and uploads files. Snapfix staff issue the keys; no app or web screen does, and nothing in the repos calls these routes. The staging data shows that both this API and the [vendor API](https://docs.snapfix.com/product/features/integrations/vendor-api.md), which uses the same keys with a vendor flag, are in use: 72 keys exist, and tasks were recently created through each. An older task API in apipy takes its own keys ([API and data](#api-and-data)).

## Rules

### Keys

* Staff create a key with `POST /v1/admin/public-simple-api`, which needs a staff sign-in and has no caller in the repos ([Staff API](https://docs.snapfix.com/engineering-reference/api/staff.md)). The request names the site, a label and a mode (`test` or `live`), and can set the vendor flag. The answer shows the key once \[[ASK-159](https://github.com/snapfix/docs/blob/main/ASK.md#ask-159-how-do-customers-and-vendors-get-api-keys)] (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/Admin/PublicSimpleAPIController.php:25-75`).
* Snapfix keeps only a hash of the key. The key starts with `sktest_` or `sklive_` and ends with a checksum; a key with a wrong checksum is refused (`app/Services/ApiKeyAuthService.php:50-70`). The mode changes nothing else: no code treats test and live keys differently.
* A key belongs to one site, and every request works inside that site (`app/Http/Middleware/AuthorizePublicApi.php:42-61`).
* A key gets a start time and no end time. The key check never reads the key's disabled flag, start or end time, and no route lists, disables, expires or deletes keys, so a key works until someone marks its row deleted or deletes its API user in the database.
* A request sends the key in the `X-API-Key` header. A missing key gets `401` "The API key is not provided", a wrong one `401` "Provided API key is not valid" (`AuthorizePublicApi.php:36-40`, `lang/en/messages.php:203-204`).
* A vendor key works here too, because this check does not test the vendor flag \[[ASK-160](https://github.com/snapfix/docs/blob/main/ASK.md#ask-160-should-a-vendor-key-also-open-the-open-api)].

### What a key can do

* Each key acts as its own API user, which Snapfix creates with the key. Its permissions are stored with the key, from a default list: view tasks, create tasks, create planned tasks, create, change and delete to-dos, delete tasks, archive tasks, create task reports, create groups, upload documents, assign users and accept assignments. Viewing group settings, changing group users and changing group tags are off (`resources/other/api_user_permission_defaults.php:5-22`).
* The routes check three of them: creating or changing a task, deleting a task, and uploading a file (`app/Policies/JobPolicy.php:212-234`).
* Reads check only that the group or task belongs to the key's site, so any group of the site can be read \[[ASK-239](https://github.com/snapfix/docs/blob/main/ASK.md#ask-239-should-an-api-key-see-every-group-and-every-task-of-its-site)]; a group or task of another site answers "not found" (`app/Policies/BusinessPolicy.php:126-133`).
* Groups are read-only: the list and one group.
* A task list is for one group, named in the required `group` value; `archivedTasks` and `normalTasks` filter it (`app/Http/Requests/v1/Public/Job/ListAssetJobRequest.php:24-27`). A task read includes its checklist items and its task chat.
* The first list, create, change or delete in a group adds the key's user to that group as an active member with the "User" role (`app/Http/Controllers/v1/Versions/v1_0/Public/JobController.php:76-81`).

### Creating, changing and deleting tasks

* A new task needs a title, and an image or a large title. It needs a group too, unless the site has AI suggestions on; then AI picks one of the site's groups from the title and description, and the create fails when it finds none ([Snapfix Recommends](https://docs.snapfix.com/product/features/ai/snapfix-recommends.md); `app/Http/Requests/v1/Public/Job/CreateAssetJobRequest.php`). The key is sent to the AI service on those calls, which does not use it.
* Checklist items need a name and a checked value; chat messages need a type and a value.
* A created task carries origin 7, made through the public API ([`enum_Origin`](https://docs.snapfix.com/engineering-reference/db/tables/enum_origin.md)), and adds one to the site's task count in the usage node that the apps read for the plan's limits ([Subscriptions](https://docs.snapfix.com/product/features/billing/subscriptions.md); `JobController.php:249`, `:258-262`).
* With AI suggestions on, AI can add tags, assignees, a room and an area after the create; it fills only what the caller left empty (`app/Jobs/ApplyAiTaskSuggestions.php:18-44`).
* A change can set the title, the image, the large title, the description and the colour, and the priority on newer app versions. A colour change writes a status line in the task chat; a change to green also writes an approval line when the group requires approval.
* Deleting a task is a soft delete: the task leaves the lists, and the site's task count goes down.
* Creating, changing and deleting a task send the usual chat lines and pushes to the group's people ([Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md)).

### Uploads and limits

* An upload is one file, an image, a video, an audio file or a document, within the server's size limit (`app/Http/Requests/v1/FileUploadRequest.php:12-27`).
* Each key gets 50,000 calls a day and 60 a minute, unless its own limits are set. Over either limit the API answers `429` until the day or the minute resets (`app/Providers/RouteServiceProvider.php:66`, `app/Http/Middleware/PublicRateLimiterMiddleware.php:31-56`).
* No plan or subscription check applies to these routes.

### Documentation

* The public API's documentation page gives `https://api.snapfix.com/v1/public/` as the base address, a separate server from the one in these repos \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)] (`app/Http/Controllers/v1/Openapi/Public/OAController.php:73`).

## Flow

```mermaid
flowchart TD
  staff["Staff create a key for one site"] --> call["Outside system sends the key in X-API-Key"]
  call --> key{"Key valid?"}
  key -- "no" --> e401["401"]
  key -- "yes" --> limit{"Within the daily and minute limits?"}
  limit -- "no" --> e429["429"]
  limit -- "yes" --> site{"Group or task in the key's site?"}
  site -- "no" --> notfound["Not found"]
  site -- "yes" --> kind{"Read or write?"}
  kind -- "read" --> read["Groups or tasks returned"]
  kind -- "write" --> perm{"Key has the permission?"}
  perm -- "no" --> denied["Access denied"]
  perm -- "yes" --> done["Task created, changed or deleted, or file stored"]
```

## Platforms

| Capability        | Web                                                                                                                                                   | iOS | Android |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------- |
| Create an API key | No screen; staff call an admin route \[[ASK-159](https://github.com/snapfix/docs/blob/main/ASK.md#ask-159-how-do-customers-and-vendors-get-api-keys)] | No  | No      |
| Use the API       | Outside systems only                                                                                                                                  | No  | No      |

## Screens

* None. No app or web screen creates or lists keys, and the staff admin app does not call the key route.

## API and data

* [Open API](https://docs.snapfix.com/engineering-reference/api/open-api.md): the public routes under `/v1/public` (groups, tasks, upload), and apipy's older task routes `GET /v1/task` and `POST /v1/task`. Every row there is marked "(no caller)" and has no section, so no endpoint is linked from this page.
* apipy's task routes take a key from [`tPri_Parent_Api`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent_api.md) in the `x-api-key` header, checked for deletion, disabling and its time window, but not against the group's site, so any active key works for any group (apipy @ 0e83c85e5a, `app.py:3756-3804`, `model/t_log_ip_blocked_v3.py:761-787`). Nothing in the repos writes that table.
* Tables: [`tPri_Api_Simple_SecretKey`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_api_simple_secretkey.md) (the keys: site, hash, permissions, limits and vendor flag), [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) (tasks and their origin) and [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md) (groups).

## Depends on

* [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md) and [Creating tasks](https://docs.snapfix.com/product/features/tasks/task-creation.md): the rules API tasks follow.
* [Groups](https://docs.snapfix.com/product/features/groups/groups.md) and [Group members](https://docs.snapfix.com/product/features/groups/group-members.md): the groups read, and the membership a first call adds.
* [Checklists](https://docs.snapfix.com/product/features/checklists/checklists.md) and [Task chat](https://docs.snapfix.com/product/features/chat/task-chat.md): what a task read includes and what a change writes.
* [Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md): the pushes a change sends.
* [Snapfix Recommends](https://docs.snapfix.com/product/features/ai/snapfix-recommends.md): the AI group choice and the fill-in after a create.
* [Vendor API](https://docs.snapfix.com/product/features/integrations/vendor-api.md): the same keys, with the vendor flag.

## Edge cases

* **Missing or wrong key:** `401` with the messages above.
* **Group or task of another site:** "not found", as if it did not exist.
* **Over a limit:** `429` until the day or the minute resets.
* **AI cannot place the task:** the create fails.
* **Leaked key:** it keeps working until someone changes the database.
* **Wrong file type or too large a file:** the upload is refused.
* **`/v1/sdk` routes:** not part of the Open API; they act as whichever user the request names.
* **Time zones:** none.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/integrations/open-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
