API reference

POST /v1/shape

Send JSON to https://api.rayonapi.com/v1/shape with Authorization: Bearer <API_KEY> and Content-Type: application/json. Supply exactly one of scripts and material_ref. Context URLs are never fetched.

Request fields
Field	Details
`mode`	Optional header (default) or form. Header behavior is unchanged.
`form`	Optional in form mode only: observed id/name strings, each at most 256 characters without controls.
`source_url`	Required page URL without credentials or fragment; preserve its query. Must match the original source context when using a reference.
`scripts`	Ordered list of {url, source}; source is full decoded JavaScript text. Use on the first call.
`material_ref`	Optional returned reference instead of scripts. Scoped to this API key and source URL.
`profile`	Required profile object. Use measured values when needed, or `{}` for server defaults. See Browser and session.
`request.url`	Required exact endpoint URL, including query parameters.
`request.method`	Required GET, HEAD, POST, PUT, PATCH, DELETE or OPTIONS.
`request.content_type`	Required content-type string or null. A non-null body needs a supported text content type.
`request.body`	Required exact UTF-8 string or null. GET/HEAD require null. Binary and multipart bodies are unsupported.
`document_cookie`	Optional source-page JavaScript-visible cookie string; default empty. Exclude HttpOnly cookies.

No proxy, IP or arbitrary fields are accepted. Keep the complete HTTP cookie jar in your target client. Both source and request domains need approved access.

Form request and response

Form mode requires POST with application/x-www-form-urlencoded and the exact encoded application request.body before telemetry insertion; empty string is allowed, null is not. It returns raw ordered form_fields and preencoded telemetry-onlyform_body, plus the same metadata, without headers. Follow Form payload integration to compose and send it once.

HTTP 200 response

Response excerpt — profile_used is shortened; values are illustrative
{
  "headers": {
    "site-prefix-a": "<generated value>",
    "site-prefix-b": "<generated value>",
    "site-prefix-c": "<generated value>",
    "site-prefix-d": "",
    "site-prefix-f": "<generated value>",
    "site-prefix-z": "<generated value>"
  },
  "request_id": "00000000-0000-4000-8000-000000000001",
  "generation_ms": 12,
  "profile_used": {
    "user_agent": "<effective browser user agent>",
    "platform": "<effective platform>"
  },
  "material_ref": "<returned material reference>",
  "material_expires_at": "2026-10-14T12:05:00Z"
}

Response fields
Field	Details
`headers`	Header mode only: six required strings with a site-specific prefix and suffixes a/b/c/d/f/z, plus optional same-family a0 freshly emitted by the uploaded scripts. Forward the entire map unchanged; the d value may be empty.
`request_id`	Correlation ID, also in X-Request-ID. Use it to find dashboard history.
`generation_ms`	Server generation time, not complete HTTP response time.
`profile_used`	Effective profile, including defaults; canvas pixels are omitted. Check the returned identity against your target client.
`material_ref, material_expires_at`	API-key-scoped, process-local material reference and its UTC expiry. Reuse does not extend expiry; eviction or restart may expire it earlier.

HTTP 200 does not mean the target website accepted the later request. No target cookies or target verification result are returned. Never append a captured a0 or infer a split from the length of a.

Direct REST fallback

Use direct REST when you need to implement validation, material references and error handling yourself. The SDK Quickstart is the recommended setup.

C# uses direct REST; there is no official C# SDK. Replace the example URLs and saved source files with your flow’s scripts. The .NET 8 example uses a GET with explicit null request fields; for POST, supply the exact body string and content type.

Generate from prepared inputs
curl --fail-with-body --max-time 45 'https://api.rayonapi.com/v1/shape' \
  -H "Authorization: Bearer $RAYON_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @shape.json

JsonSerializer.Serialize safely escapes the JavaScript without changing its decoded text. Serialize the object once; if you already have JSON text, send that text directly instead of serializing the string again. Keep default null serialization so required request fields remain present.

Omit the unused material field completely; do not add material_ref: null to a scripts upload. To reuse material, replace scripts with the returned reference, retaining the exact source URL and current profile, request and applicable document-cookie inputs. See material reuse for expiry and billing-aware recovery.

Input limits

Request limits
Field	Details
`Upload`	4 MiB compressed and expanded JSON; Content-Encoding identity or gzip. Upload deadline: 20 seconds.
`Scripts`	1–16 scripts; 2 MiB each; 3 MiB total UTF-8 source.
`Body`	256 KiB UTF-8. Content type: 256 characters.
`Form input`	At most 1,024 decoded application pairs; 256 UTF-8 bytes per field name. Invalid percent escapes, UTF-8 and NUL are rejected.
`Form output`	At most 16 KiB UTF-8 per opaque value without C0 controls or DEL; 256 KiB encoded telemetry body.
`Cookies`	document_cookie: 16 KiB; no CR, LF or NUL.
`URLs`	8,192 characters; HTTP/S only; no credentials, fragments, whitespace or backslashes.
`Profile`	64 KiB after defaults and alias expansion. See profile field bounds.
`JSON`	32 levels; 4,096 structural nodes. Unknown fields, duplicate/prototype keys and nonfinite numbers are rejected.

Download the OpenAPI schema. For response errors, see Errors and limits.