Structured extraction

Supply a JSON Schema in the jsonSchema field and the response body becomes the structured data extracted from the page and coerced into your schema — instead of the raw page response.

curl https://request.usestring.ai/v1/fetch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example.com/listing/123",
    "jsonSchema": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "price": { "type": ["number", "null"] },
        "condition": { "type": "string", "enum": ["New", "Used"] }
      },
      "required": ["title"]
    }
  }'

The response is the coerced object:

{ "title": "2027 Keystone COUGAR 316RLS", "price": 69674, "condition": "New" }

Rules and bounds

• Must be a valid JSON Schema object — shorthand like { "title": "string" } is rejected with a 400.
• format must be json (the default). Supplying jsonSchema with format: raw or format: markdown is a 400.
• Bounds: maximum nesting depth 10, maximum 200 keys, and 50 KB when serialized.
• List the fields you require in the schema's required array.

Fallback behavior

If extraction can't produce the fields you marked as required, the request returns a fallback envelope rather than a partial object. It keeps the standard format: json fields, so the page still reaches you as data:

{
  "statusCode": 200,
  "headers": { "content-type": ["text/html; charset=utf-8"] },
  "data": "<html>…</html>",
  "extracted": false,
  "reason": "schema_mismatch"
}

Detecting a fallback

Every fallback carries the same machine-readable outcome in its body and response headers. If your integration only reads the body, check for extracted: false and branch on reason. Successful extraction still returns your bare schema object, without a wrapper.