POST /parsers-engine-rpc

Execute the Parsers Engine against a given input and Parsers Rules.

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

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

Name	Type	Description
dataBox	ParsersEngineDataBox	The initial state to launch the parsers engine from.
rules	Array<ParserRule>	The parser rule definitions to instruct the transformation and generation pipelines.
returnedKeys	Record<string, boolean | undefined> | undefined	Select which response keys should be present. Defaults to true.

Response Body

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;
  }>;
}>;

The response is an array where each item is the result of the rule given in the request, at the same index.

The output type matches the output configured within the rule given in the request.

The route always respond with a 200 code. Error state is represented by the status property in response object.

Example

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

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"
          }
        }
      ]
    }
  ]
}'