> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spidra.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Preset

> Save a template with its inputs, or any tool's request, to run again with one call.

A preset is a saved job. There are two kinds:

* **Template preset** (`kind: "template"`): a template and its inputs, such as Google Maps leads for dentists in Lekki.
* **Tool preset** (`kind: "tool"`): the request body for scrape, batch, crawl, map, search or parse, exactly as you would send it to that endpoint.

Run either with [Run a Preset](https://docs.spidra.io/api-reference/presets/run.md), or [watch it for changes](https://docs.spidra.io/monitors.md).

## Template preset

```bash theme={null}
curl -X POST https://api.spidra.io/api/presets \
  -H "Authorization: Bearer $SPIDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "template",
    "name": "Dentists in Lekki",
    "template": "google-maps-leads",
    "inputs": { "query": "dentist", "areas": ["Lekki, Lagos"] }
  }'
```

```json theme={null}
{
  "status": "success",
  "message": "Preset saved.",
  "data": { "uuid": "15415447-7680-4dc5-90a0-f7a900c7f418", "id": "15415447-7680-4dc5-90a0-f7a900c7f418" }
}
```

The inputs are checked the same way a run checks them, and missing defaults are filled in. Add `columns` to save which columns the dashboard table shows.

## Tool preset

```bash theme={null}
curl -X POST https://api.spidra.io/api/presets \
  -H "Authorization: Bearer $SPIDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "tool",
    "name": "Python docs: asyncio pages",
    "tool": "map",
    "config": { "url": "https://docs.python.org/3/", "search": "asyncio", "limit": 5 }
  }'
```

`config` must have what the tool requires: `urls` for scrape and batch, `baseUrl` for crawl, `url` for map, `query` for search, and `url` or `fileId` for parse. `cookies` and `wait` are never stored, so a preset never keeps a login.

## Errors

| Status | When |
| - | - |
| `400` | No `name`, an unknown `tool`, or a `config` that isn't an object. |
| `404` | No template with this slug. |
| `422` | Template inputs that need fixing (`errors` lists them), or a tool `config` missing a required field: `The crawl settings are missing: baseUrl.` |


## OpenAPI

````yaml POST /presets
openapi: 3.1.0
info:
  title: Spidra API
  version: 1.0.0
  description: >-
    Public API endpoints for web scraping via Spidra. Authenticate with
    `Authorization: Bearer YOUR_API_KEY`.
servers:
  - url: https://api.spidra.io/api
security:
  - BearerAuth: []
  - ApiKeyAuth: []
paths:
  /presets:
    post:
      tags:
        - Presets
      summary: Create a Preset
      description: >-
        Saves a template with its inputs, or a tool's request, to run again
        later.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - title: Template preset
                  type: object
                  required:
                    - kind
                    - name
                    - template
                    - inputs
                  properties:
                    kind:
                      type: string
                      enum:
                        - template
                    name:
                      type: string
                    description:
                      type: string
                    template:
                      type: string
                      description: The template's slug.
                    inputs:
                      type: object
                      description: The template's inputs. Checked like a run.
                    columns:
                      type: array
                      items:
                        type: object
                        properties:
                          key:
                            type: string
                          label:
                            type: string
                          format:
                            type: string
                      description: Optional. The columns the dashboard table shows.
                - title: Tool preset
                  type: object
                  required:
                    - kind
                    - name
                    - tool
                    - config
                  properties:
                    kind:
                      type: string
                      enum:
                        - tool
                    name:
                      type: string
                    description:
                      type: string
                    tool:
                      type: string
                      enum:
                        - scrape
                        - batch
                        - crawl
                        - map
                        - search
                        - parse
                    config:
                      type: object
                      description: >-
                        The request body you would send to the tool, such as `{
                        "url": "...", "search": "..." }` for map. `cookies` and
                        `wait` are never stored.
            example:
              kind: template
              name: Dentists in Lekki
              template: google-maps-leads
              inputs:
                query: dentist
                areas:
                  - Lekki, Lagos
      responses:
        '201':
          description: Saved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      uuid:
                        type: string
                        description: Same as `id`.
        '400':
          description: A missing name, an unknown tool, or a config that isn't an object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No template with this slug.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Some inputs need fixing. `errors` lists each field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidInputError'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        message:
          type: string
      required:
        - status
        - message
    InvalidInputError:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        code:
          type: string
          enum:
            - INVALID_INPUT
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
          description: One entry per field that needs fixing.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.