Parse JSON

Paid Action: This action consumes credits based on the amount of content parsed. See more below.

Type: parse_json

The parse_json action extracts data from web pages and online PDFs. It uses AI to parse web content from text into a pre-defined data schema and return it as a JSON object.

The action lets you convert unstructured content, such as academic papers, forms, and webpages, into JSON objects that you can use in automations, analysis, or further processing.

This feature currently works for online PDFs and web page text.

Tips for using parse_json

• Prefer a deterministic action where one exists. AI parsing is powerful, but an action that reads the page directly gives the same answer every time — parse_table is the obvious example when the data is in an HTML table.
• Add a selector so the model only sees the part of the page you care about. It's cheaper, faster and more accurate.
• Write field descriptions as instructions, not labels. Say what format you want and what to do when a value is missing.
• The more specific your descriptions and instructions, the better the result.
• Use input_token_cap and max_pages to keep costs predictable on jobs you run often.
• Save schemas you reuse with POST /v1/schemas and call them with data_schema_id.
• Use output_type: "inline" to get the JSON back in the response instead of a file URL.

Parameters

Required

Name	Type	Required	Description
data_schema_id	string		The id of the data schema you have defined that you want to transform the content into. You must provide a data_schema or data_schema_id with your request.
data_schema	json		A JSON object describing the data_schema you want to transform the content into. You must provide a data_schema or data_schema_id with your request.
instruction	string		A custom instruction, in addition to any detail you have added to the data schema, that you want to include with this particular parse.
model	string		The AI model you wish to use to parse the content into JSON. Default: gpt-4o-mini Accepted: ["gpt-4o-mini"]
input_token_cap	int		The max number of source input tokens that will be passed to the AI model to parse. This can be used to prevent unnecessary credit usage. If your source input is longer than the token cap, it will be abbreviated. Default: 1,000,000
selector	string		The selector that defines an element you want to parse the content of - this is useful if you are only interested in the contents of a certain element.
output_type	string		Should the action output be saved to a file where a URL will be returned or should the parsed JSON object be included directly in the request. Default: file Accepted: ["file", "inline"]
max_pages	int		If you are parsing a PDF you can specify this parameter to limit the number of pages that are passed to the LLM. Default: no limit

See universal parameters.

Defining Data Schemas

A data schema tells the model exactly what JSON structure to produce.

You can define schemas in two ways:

• Inline schemas (defined directly inside the action)
• Reusable schemas (created via the Schema API and referenced by ID in your requests)

Schema Structure

A schema has:

Property	Type	Description
description	string	Explains what data the schema extracts and provides context to help the AI model understand the extraction goal. Example: "Extract product details from this e-commerce product page"
fields	array	Each field defines a piece of data to extract from the content. See field properties below.
name	string	This identifies the schema and should clearly indicate what data it extracts. Example: "ProductInfo", "ArticleMetadata", "ContactForm"

Each field in the fields array has:

description	string	Include details about format, handling of missing values, or special cases. Example: "Maximum salary in GBP. If only one value is provided, use the same value for both min and max. Return null if not provided."
fields	array	Required only for object and array types.
name	string	Use clear, descriptive names that follow your preferred naming convention (e.g., snake_case or camelCase). Example: "product_name", "published_date", "author_email"
type	string	Determines how the AI interprets and structures the extracted data. Must be one of the supported types below.

Supported Field Types

Type	Description
array	List of items
boolean	True/False
datetime	timestamp
decimal	Precise decimal
double	Floating-point number
integer	Whole number
object	Nested structured object
string	Text value

Inline Schema Example

"actions": [
  {
    "type": "parse_json",
    "model": "gpt-4o-mini",
    "output_type": "inline",
    "instruction": "Extract metadata from an article",
    "data_schema": {
      "name": "ArticleMetadata",
      "description": "Schema for parsing article Metadata",
      "fields": [
        {
          "type": "string",
          "name": "title",
          "description": "Article title"
        },
        {
          "type": "string",
          "name": "author",
          "description": "Author name"
        },
        {
          "type": "datetime",
          "name": "published",
          "description": "Publication date"
        }
      ]
    },
  }
]

This example shows:

• Simple fields (string, datetime) for basic data
• Object fields for grouped related data with nested fields
• Array fields for lists of items with nested fields defining each item's structure

Schema Operations

Instead of defining schemas inline each time, you can save them to your Gaffa account and reuse them across multiple requests. This makes your actions more readable, easier to maintain, and ensures consistency when parsing similar content.

Creating a Saved Schema

Use the POST /v1/schemas endpoint to create a reusable schema:

curl -L \
  --request POST \
  --url 'https://api.gaffa.dev/v1/schemas' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "ProductInfo",
    "description": "Extract product details from e-commerce pages",
    "fields": [
      {
        "type": "string",
        "name": "product_name",
        "description": "The product title"
      },
      {
        "type": "decimal",
        "name": "price",
        "description": "Current price"
      },
      {
        "type": "boolean",
        "name": "in_stock",
        "description": "Product availability"
      },
      {
        "type": "object",
        "name": "ratings",
        "description": "Product rating information",
        "fields": [
          {
            "type": "double",
            "name": "average",
            "description": "Average rating score"
          },
          {
            "type": "integer",
            "name": "total_reviews",
            "description": "Number of reviews"
          }
        ]
      },
      {
        "type": "array",
        "name": "tags",
        "description": "Product tags",
        "fields": [
          {
            "type": "string",
            "name": "tag",
            "description": "Individual tag name"
          }
        ]
      }
    ]
  }'

Response:

{
  "id": "schema_abc123xyz",
  "name": "ProductInfo",
  "description": "Extract product details from e-commerce pages",
  "fields": [...]
}

Save the id returned in the response, you'll use this to reference the schema in your requests

Managing Schemas

List all schemas:

Allows you to view all schemas saved to your account:

Endpoint: GET /v1/schemas

curl -L \
  --url 'https://api.gaffa.dev/v1/schemas' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Accept: */*'

Update a schema:

Allows you to modify an existing schema by its ID:

Endpoint: PUT /v1/schemas

curl -L \
  --request PUT \
  --url 'https://api.gaffa.dev/v1/schemas/{id}' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "schema_abc123xyz",
    "name": "ProductInfo",
    "description": "Extract detailed product information from e-commerce pages",
    "fields": [
      {
        "type": "string",
        "name": "product_name",
        "description": "The product title"
      },
      {
        "type": "decimal",
        "name": "price",
        "description": "Current price"
      },
      {
        "type": "string",
        "name": "brand",
        "description": "Product brand name"
      }
    ]
  }'

Delete a schema:

Removes a schema from your account:

Endpoint: DELETE /v1/schemas/:id

curl -L \
  --request DELETE \
  --url 'https://api.gaffa.dev/v1/schemas/{id}' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Accept: */*'

Common Schema Patterns

Simple List Extraction

{
  "name": "TagList",
  "description": "Extract article tags",
  "fields": [
    {
      "type": "array",
      "name": "tags",
      "description": "List of article tags",
      "fields": [
        {
          "type": "string",
          "name": "tag",
          "description": "Individual tag name"
        }
      ]
    }
  ]
}

Nested Objects

{
  "name": "ProductWithReviews",
  "description": "Product details with nested review data",
  "fields": [
    {
      "type": "string",
      "name": "product_name",
      "description": "Product name"
    },
    {
      "type": "object",
      "name": "pricing",
      "description": "Pricing information",
      "fields": [
        {
          "type": "decimal",
          "name": "current_price",
          "description": "Current price"
        },
        {
          "type": "decimal",
          "name": "original_price",
          "description": "Original price before discount"
        },
        {
          "type": "integer",
          "name": "discount_percentage",
          "description": "Discount percentage"
        }
      ]
    }
  ]
}

Pricing

The credits this action uses depend on the model used. Here are the current supported models and their pricing:

Model	Input Token Cost	Output Token Cost
gpt-4o-mini	1 credit per 20,000 input tokens	1 credit per 10,000 output tokens

FAQs

When do I use the parse_json action?

Use it when you need specific fields from content that isn't already structured, such as an article, a PDF, a product page, or a form. It uses AI to fit the content into a schema you define.

Does parse_json return the same result every time?

Not necessarily. Because it uses an AI model, running the same request twice can produce slightly different output, particularly for summaries or free-text fields.

How do I extract structured data from a web page?

Add a parse_json action with a data_schema listing the fields you want, or point at a saved schema with data_schema_id. Gaffa returns the content in that structure.

What's the difference between data_schema and data_schema_id?

data_schema defines the structure inside the action itself. data_schema_id points to a schema you've saved to your account. Send one or the other with every request.

How do I keep parse_json costs down?

Narrow the input with selector, cap it with input_token_cap, and limit PDFs with max_pages. Use parse_table instead whenever the data is already in an HTML table.

How do I get more accurate results from parse_json?

The more specific your instructions, the better the result. Describe each field's format, units and what to do when a value is missing; add an instruction for context, and use selectors so the model sees less noise.

What field types can I use in a schema?

string, integer, decimal, double, boolean, datetime, object and array. Object and array fields need a nested fields list describing what's inside them.

Can parse_json read a PDF?

Yes, it works on online PDFs as well as web pages. Use max_pages to limit how many pages get sent to the model, which keeps costs down on long documents.

How do I extract a list of items?

Use an array field with a nested fields list describing each item. For a simple list, nest one string field. For records, nest one field per property.

When should I use parse_table instead of parse_json?

Use parse_table when the data is in a real HTML table. It's exact, gives the same result every time, and costs no credits.