# Print farm quickstart

For print farms.

The print farm API lets a production partner read the orders allocated to its farm, report their progress, and read the products, stocks and materials it produces.

The print farm API keeps the conventions it was built with: numbered pages instead of cursors, and its own error body. Its ids and field names are its own too, so the conventions in the designer and integrator guides do not apply here.

## The base URL

Every path starts with `/v1/print-farm`. The examples read the API base URL from `DAPI_API_URL` and your key from `DAPI_API_KEY`.

**Shell**

```bash
export DAPI_API_URL="<the API base URL>"
export DAPI_API_KEY="<your API key>"
```

All requests and responses are JSON over HTTPS.

## API keys and permissions

Send an API key in the `x-api-key` header. Keys are created in the print farm dashboard. Each operation needs one of the permissions it lists; a key with `FULL` has them all.

Permissions: `READ_ORDERS`, `WRITE_ORDERS`, `SKU`, `READ_STOCK`, `WRITE_STOCK`, `FULL`.

Create and revoke keys on the API keys page of your dashboard (print farms: [https://dapi.digital/print-farm/public-api-keys](https://dapi.digital/print-farm/public-api-keys)). Keep them on your server.

-   `READ_ORDERS`: [List orders allocated to your print farm](https://public-api.dapi.digital/docs/reference/print-farm-orders.md#listPrintFarmOrders), [Get one order allocated to your print farm](https://public-api.dapi.digital/docs/reference/print-farm-orders.md#getPrintFarmOrder)
-   `WRITE_ORDERS`: [Transition an order to a new status](https://public-api.dapi.digital/docs/reference/print-farm-orders.md#updatePrintFarmOrderStatus)
-   `SKU`: [List SKUs visible to your print farm](https://public-api.dapi.digital/docs/reference/print-farm-skus.md#listPrintFarmSkus), [Get one SKU visible to your print farm](https://public-api.dapi.digital/docs/reference/print-farm-skus.md#getPrintFarmSku), [List approved designs visible to your farm](https://public-api.dapi.digital/docs/reference/print-farm-designs.md#listPrintFarmDesigns), [Get one approved design visible to your farm](https://public-api.dapi.digital/docs/reference/print-farm-designs.md#getPrintFarmDesign), [List approved extras visible to your farm](https://public-api.dapi.digital/docs/reference/print-farm-extras.md#listPrintFarmExtras), [Get one approved extra visible to your farm](https://public-api.dapi.digital/docs/reference/print-farm-extras.md#getPrintFarmExtra), [List materials visible to your farm](https://public-api.dapi.digital/docs/reference/print-farm-materials.md#listPrintFarmMaterials), [Get one material visible to your farm](https://public-api.dapi.digital/docs/reference/print-farm-materials.md#getPrintFarmMaterial)
-   `READ_STOCK`: [List stock levels at your print farm](https://public-api.dapi.digital/docs/reference/print-farm-stock-levels.md#listPrintFarmStockLevels), [Get one stock level at your print farm](https://public-api.dapi.digital/docs/reference/print-farm-stock-levels.md#getPrintFarmStockLevel), [List stocks visible to your print farm](https://public-api.dapi.digital/docs/reference/print-farm-stocks.md#listPrintFarmStocks), [Get one stock visible to your print farm](https://public-api.dapi.digital/docs/reference/print-farm-stocks.md#getPrintFarmStock)
-   `WRITE_STOCK`: [Add items printed to a stock level](https://public-api.dapi.digital/docs/reference/print-farm-stock-levels.md#addPrintFarmStockLevelItemsMade)
-   Any valid key: [List available courier options](https://public-api.dapi.digital/docs/reference/print-farm-courier-options.md#listPrintFarmCourierOptions)

## Make your first request

[List your orders](https://public-api.dapi.digital/docs/reference/print-farm-orders.md#listPrintFarmOrders) returns the orders allocated to your farm, newest first. It is the quickest way to check that a key works.

**GET /v1/print-farm/orders (curl)**

```bash
curl "https://public-api.dapi.digital/v1/print-farm/orders" \
  -H "x-api-key: $DAPI_API_KEY"
```

**GET /v1/print-farm/orders (Node.js)**

```javascript
const response = await fetch(`${process.env.DAPI_API_URL}/v1/print-farm/orders`, {
  headers: {
    'x-api-key': process.env.DAPI_API_KEY,
  },
});
const data = await response.json();
```

**GET /v1/print-farm/orders (Python)**

```python
import os
import requests

response = requests.get(
    f"{os.environ['DAPI_API_URL']}/v1/print-farm/orders",
    headers={"x-api-key": os.environ["DAPI_API_KEY"]},
)
data = response.json()
```

## Pages

Lists are numbered pages. Ask for one with these query parameters:

-   `page` (integer): 1-based page index.
    
    Range at least 1. Defaults to 1.
    
-   `page_size` (integer): Page size (max 100).
    
    Range 1 to 100. Defaults to 20.
    

Next to the items, a list response says where you are:

-   `page` (number): Page number returned, matching the `page` query parameter.
    
    Range at least 1.
    
-   `page_size` (number): Number of items per page, matching the `page_size` query parameter.
    
    Range 1 to 100.
    
-   `total` (number): Total number of orders across all pages (after filters are applied).
    
    Range at least 0.
    

## Errors

Errors have the body `{ "statusCode", "error", "message" }`. `message` is a string, or a list of strings when the request failed validation.

**Error**

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or inactive API key."
}
```

## Rate limits

Requests are limited to 500 per 60-second window per API key. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.

---

3DAPI API Docs. This page on the web: https://public-api.dapi.digital/docs/guides/print-farm-quickstart. Index of every page: https://public-api.dapi.digital/docs/llms.txt.
