# Introduction

What the Skillful Sardine API does, how a call looks and what every response contains.

The Skillful Sardine API is a set of small operations for the work automations do all the time: parsing CSV, reshaping JSON, comparing lists, cleaning text, working with dates, reading PDFs and generating identifiers. Each operation does one thing, and every operation answers in the same shape, so a flow can rely on it.

## How a call looks

Operations are `POST` calls with a JSON body, under the `/v1` path. This call parses a small CSV file:

```http
POST /v1/csv/parse
Content-Type: application/json

{"content": "name,city\nAna,Porto\n"}
```

## What every response contains

Every response, successful or not, has the same three keys:

| Key | What it holds |
| --- | --- |
| `data` | The result of the operation. `null` when the call failed. |
| `errors` | A list of problems, each with a `code`, a `message` and, for invalid input, the `field`. `null` when the call worked. |
| `meta` | The `request_id` of the call, its `timestamp` and the API `version`. Quote the `request_id` when you ask for help. |

The call above answers:

```json
{
  "data": {
    "headers": ["name", "city"],
    "records": [{"name": "Ana", "city": "Porto"}],
    "rows": [["Ana", "Porto"]],
    "row_count": 1,
    "warnings": []
  },
  "errors": null,
  "meta": {
    "request_id": "99fedbdb-61db-455f-b435-0f18f033540a",
    "timestamp": "2026-10-20T15:53:06.512988Z",
    "version": "2026-03-26"
  },
  "pagination": null
}
```

## When something goes wrong

A problem with the input answers `400` (or `422` when a field is missing or has the wrong type) and says what to fix. Sending an empty CSV answers:

```json
{
  "data": null,
  "errors": [{"code": "http_error", "message": "The CSV is empty. Send at least one row", "field": null}],
  "meta": {"request_id": "55906c68-0028-4134-a0ab-ab375c91d251", "timestamp": "2026-10-20T15:53:06.516408Z", "version": "2026-03-26"},
  "pagination": null
}
```

Every operation in the reference lists its fields, which ones are required and their defaults. [Errors](../errors/) explains every status a call can answer.

---
Source: https://skillfulsardine.com/developers/api/introduction/