> For the complete documentation index, see [llms.txt](https://docs.specifyapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.specifyapp.com/reference/http-api/post-parsers-engine-rpc.md).

# POST /parsers-engine-rpc

## Route

**Method:** `POST`

**Authentication:** `required`

**Url:**

```
https://api.specifyapp.com/v2/parsers-engine-rpc
```

### Headers

```
Content-Type: application/json
Authorization: PAT <your-personal-access-token>
```

### Request Body

```typescript
type ParsersEngineRPCRequestBody = {
  dataBox: ParsersEngineDataBox;
  rules: Array<ParserRule>;
  returnedKeys?: {
    output?: boolean;
    next?: boolean;
    errorMessages?: boolean;
    warningMessages?: boolean;
    informationMessages?: boolean;
  };
};
```

<table><thead><tr><th>Name</th><th width="291">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>dataBox</code></td><td><a href="/pages/BE8GV64z8L12OkglNmN2#parsersenginedatabox"><code>ParsersEngineDataBox</code></a></td><td>The initial state to launch the parsers engine from.</td></tr><tr><td><code>rules</code></td><td><code>Array&#x3C;</code><a href="/pages/BE8GV64z8L12OkglNmN2#parserrule"><code>ParserRule</code></a><code>></code></td><td>The parser rule definitions to instruct the transformation and generation pipelines.</td></tr><tr><td><code>returnedKeys</code></td><td><code>Record&#x3C;string, boolean | undefined> | undefined</code></td><td>Select which response keys should be present. Defaults to <code>true</code>.</td></tr></tbody></table>

### Response Body

```typescript
type ParsersEngineResults = Array<{
  pipelineName: string;
  isFromRule: boolean;
  status: "success" | "error";
  output:
    | {
        type: "files";
        files: Array<{
          path: string;
          content:
            | { type: "text"; text: string }
            | { type: "url"; url: string };
        }>;
      }
    | {
        type: "JSON";
        json: unknown;
      }
    | {
        type: "text";
        text: string;
      }
    | {
        type: "SDTF";
        graph: SpecifyDesignTokenFormat;
      }
    | null;
  next: ParsersEngineDataBox | undefined;
  errorMessages: Array<{
    type: "error";
    content: string;
    errorKey: string;
  }>;
  warningMessages: Array<{
    type: "warning";
    content: string;
    errorKey: string;
  }>;
  informationMessages: Array<{
    type: "information";
    content: string;
  }>;
}>;
```

{% hint style="info" %}
The response is an array where each item is the result of the rule given in the request, at the same index.
{% endhint %}

{% hint style="info" %}
The output type matches the output configured within the rule given in the request.
{% endhint %}

{% hint style="warning" %}
The route always respond with a 200 code. Error state is represented by the `status` property in response object.
{% endhint %}

## Example

Here's a simple example to get the raw tokens in JSON from a repository called `all-design-data`in the `@acme-inc` workspace:

```bash
curl -X POST 'https://api.specifyapp.com/v2/parsers-engine-rpc' \
--header 'Authorization: PAT <YOUR-PERSONAL-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "dataBox": {
    "type": "repository",
    "owner": "@acme-inc",
    "name": "all-design-data"
  },
  "rules": [
    {
      "name": "HTTP Extract",
      "parsers": [
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "tokens.json"
          }
        }
      ]
    }
  ]
}'
```