---
title: "Read a Ploti guide"
method: POST
path: "/v1/tools/read_guide"
---

# Read a Ploti guide

`POST /v1/tools/read_guide`

## Request

- Base URL: `https://api.ploti.ai`
- URL: `https://api.ploti.ai/v1/tools/read_guide`
- Auth: HTTP bearer

Fetch a guide on how to work with Ploti's data and sandbox. Call without an id to list them. 'discovering-data' is worth reading for any task; for a quick single lookup it is often enough. Read the others when the task calls for them: 'navigation' before choosing where and how close to look, 'querying' before your first substantial SQL, 'parcel-data' before filtering parcels, 'spatial-analysis' before cross-layer spatial work, 'map-rendering' before custom-colored maps, 'ordinances' before municipal-code research, 'delivering-results' before creating checkpoints, tables, or files for the user, 'satellite-imagery' before rendering map images, 'branded-pdf-reports' before any PDF. python/<module> ids (python/checkpoint, python/schema, ...) return the exact deployed signatures — read one before your first call into that module. A guide read once stays read for the conversation; most questions need two or three, so read them together in one call with guide_ids.

## Request body

- object
  - `guideId` string: One guide to read, by the id this tool lists, e.g. 'querying' or 'python/database'. Leave out both ids to list the guides.
  - `guideIds` string[]: Guides to read together in one call, e.g. ['discovering-data', 'parcel-data']; read along with guide_id when both are given.

## Response `200`

What the tool returned: its text, any images, and structured data.

- object
  - `text` string, required
  - `images` object[], required
    - `mimeType` string
    - `data` string, byte
  - `data` unknown

## Other responses

- `400`: invalid_input: the arguments do not fit the tool's input schema.
- `403`: insufficient_scope: the credential may not use this tool.
- `404`: not_found: there is no such tool.
- `413`: payload_too_large: the body is over 256 KB (2 MB for /v1/tools).
- `415`: unsupported_media_type: a body was sent without Content-Type: application/json.
- `422`: tool_error: the tool refused or failed; error.message says why.
- `429`: rate_limited: this credential is over its rate. Retry after the Retry-After header's seconds.
- `500`: internal: Ploti failed. Retry; if it keeps happening, contact support.

---

[API](https://skmtc.dev/ploti/apis/ploti-api.md) · [All operations](https://skmtc.dev/ploti/apis/ploti-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ploti/apis/ploti-api/revisions/8c2c91c72d52?raw)