> For the complete documentation index, see [llms.txt](https://support.pipefile.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.pipefile.com/api-reference/overview.md).
# API overview
Send requests, read their progress and manage contacts and webhooks from your own software.
The Pipefile API lets your own software do what your team does in the dashboard: send requests, check how far along they are, list your templates, keep your contacts in sync and register webhooks that tell you when something happens.
| You want to | Use |
| ------------------------------------------------------ | --------------------------------------------------------- |
| Send a request with a checklist you build in code | `POST /file/request/` |
| Send a request from a saved template | `POST /file/request/create_from_template/` |
| Find requests by status, tag, date or keyword | `GET /file/requests/` |
| Read one request's checklist, reviews and open history | `GET /file/request/{request_id}/detail/` |
| List your templates | `GET /file/request/templates/` |
| Create, read, update and delete contacts | `/contacts/` |
| Get notified when a request changes | `/webhooks/` (see [Webhooks](/api-reference/webhooks.md)) |
The full reference for every endpoint, field and response is in the API Reference section.
## Base URL
```
https://api.pipefile.com/v1
```
Every path ends with a slash, for example `https://api.pipefile.com/v1/contacts/`. Send and receive JSON with `Content-Type: application/json`.
## Plan availability
API keys are available on every plan, including Free. Your plan's normal limits still apply to requests you send through the API. On the Free plan you can have one open request at a time, so a create call that would go over that limit returns `402`.
## Get an API key
{% stepper %}
{% step %}
### Open API keys
Go to [**Settings** › **API keys**](https://pipefile.com/dashboard/settings/api).
{% endstep %}
{% step %}
### Create the key
Click **New API key**. Name it after whatever will use it, such as "CRM sync", so you can tell your keys apart later. Names can be up to 100 characters. Click **Create key**.
{% endstep %}
{% step %}
### Copy it now
Copy the key and store it somewhere safe, such as your secrets manager. This is the only time Pipefile shows it. If you lose it, revoke it and create another one.
{% endstep %}
{% endstepper %}
The **API keys** page lists each key with when it was created, when it was last used, when it expires, and its status (**Active**, **Expired** or **Revoked**). Pipefile emails you whenever a key is created or revoked.
{% hint style="info" %}
A key acts as you. It sees the same requests, templates and contacts you see in the dashboard, and anything it creates is owned by you.
{% endhint %}
### Expiry and revoking
A key expires a year after it was last used, so a key in regular use keeps working. Every key stops working two years after it was created at the latest, so plan to replace long-lived keys.
To stop a key working immediately, click **Revoke** next to it. Revoking cannot be undone. It does not undo what the key already did: requests it sent and webhooks it registered keep working.
You can create up to 10 keys an hour.
## Authentication
Send the key in the `Authorization` header with the `Token` prefix. `Bearer` does not work.
```bash
curl https://api.pipefile.com/v1/contacts/ \
-H "Authorization: Token YOUR_API_KEY" \
-H "Content-Type: application/json"
```
### Sending as a teammate
If you are a team admin, you can send a request from a template as one of your team members. Add the `X-Pipefile-On-Behalf-Of` header with their Pipefile email address to `POST /file/request/create_from_template/`. The request is owned by them and reaches the recipient from them. The member must be active on your team. Every other endpoint rejects the header with `400`.
## Pagination
`GET /file/requests/` and `GET /contacts/` return 25 results per page:
```json
{
"count": 50,
"num_pages": 2,
"next": "...",
"previous": null,
"results": [ ... ]
}
```
Ask for a page with `page` (starting at 1) and change the size with `page_size` (up to 100). Loop until `page` reaches `num_pages`. The template and webhook lists are not paginated and return a plain array.
## Errors
Errors come back as JSON with a standard HTTP status.
| Status | Meaning | Body |
| ------ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `400` | A field is missing or not valid | Field names, each with a list of messages: `{"expiration_date": ["This field is required."]}` |
| `402` | Your plan's open-request limit is reached | `{"detail": "..."}` |
| `403` | The key is missing, wrong or revoked, or you don't have access to that item | `{"detail": "Invalid token."}` |
| `404` | Nothing with that ID exists | `{"detail": "Not found."}` |
| `429` | Too many calls | `{"detail": "Request was throttled. Expected available in 12 seconds."}` |
A missing or invalid key returns `403`, not `401`.
## Rate limits
Each account can make up to 300 calls a minute and 5,000 calls an hour. Past either limit, calls return `429` with the number of seconds to wait.
Why does creating a request return "file_pipe: This field is required"?
`POST /file/request/` needs `file_pipe.key`, the ID of the encryption key that protects uploads, plus `attachments` (an empty array is fine) on the request and on every checklist item, `tags` and `expiration_date`. Read your key's ID from `file_pipe.key.id` on any request you already have. If you don't need to build the checklist in code, send from a template instead: `POST /file/request/create_from_template/` needs only the template ID and the recipient.
Can I upload files or review documents through the API?
No. The API sends requests and reads their status. Reviewing, downloading and exporting files happen in the dashboard, or automatically through [cloud storage auto-export](https://app.gitbook.com/s/5FaOvSTk88hXbQhqEN0A/reviewing-and-exporting/cloud-storage-and-auto-export).
## Related
* [Webhooks](/api-reference/webhooks.md)
* [Zapier](/api-reference/zapier.md)
* [Contacts](https://app.gitbook.com/s/5FaOvSTk88hXbQhqEN0A/team-and-account/contacts)
---
# 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://support.pipefile.com/api-reference/overview.md?ask=&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.