Shared types and security
Use with your agent
Give this prompt to your AI agent. The agent does the task for you.
Read https://thirds.ai/docs/api-reference/shared and help me choose the right thirds.ai endpoint and write a request. Check the fields and credentials in this reference.
Look up shared request and response fields, error types, response headers, and API authentication schemes.
See all API resources or read API keys and requests.
Schemas
FieldDetail
One request field that failed, its fixed safe reason, and an optional bounded source location. Details never carry template source, customer values, rendered output, or raw evaluator prose.
| Field | Required | Description and type |
|---|---|---|
field | Yes | The path to the field, such as "pdf.scale". Schema errors use data followed by a JSON Pointer, such as data/items/0/count. The pointer is cut at 256 UTF-8 bytes. Empty for a problem with the whole document. {"type":"string","maxLength":260} |
reason | Yes | A fixed, safe reason. It never repeats the value the caller sent. {"type":"string","enum":["malformed JSON","missing field","unknown field","wrong type","invalid value","A required value is missing.","Use the expected value type.","Declare this variable before using it.","Choose an allowed value.","Use the required format.","Add a value.","Use a shorter value.","Use a number within the allowed range.","Check this value against its data rule."]} |
line | No | The one-based template source line when the evaluator provides one within the published bound. {"type":"integer","minimum":1,"maximum":1000000} |
column | No | The one-based template source column when the evaluator provides one within the published bound. {"type":"integer","minimum":1,"maximum":1000000} |
Schema rules: {"type":"object","additionalProperties":false}.
BrandKitId
Schema rules: {"type":"string","pattern":"^kit_[0-9a-f]{32}$"}.
TemplateId
Schema rules: {"type":"string","pattern":"^tpl_[0-9a-f]{32}$"}.
ArchivePeriod
| Field | Required | Description and type |
|---|---|---|
archived_at | Yes | {"type":"string","format":"date-time"} |
restored_at | Yes | {"type":["string","null"],"format":"date-time"} |
Schema rules: {"type":"object","additionalProperties":false}.
PlanLimitInfo
Present when the account's plan causes the refusal: brand_kit_limit and batch_row_limit. It names the limit and the plan that sets it, so a caller can act without a second request. The message text never names the number.
| Field | Required | Description and type |
|---|---|---|
plan | Yes | The account's plan at the time of the refusal. {"type":"string","enum":["scale","growth","starter","pack","free"]} |
limit | Yes | What that plan allows: brand kits for brand_kit_limit, rows in one run for batch_row_limit. {"type":"integer","minimum":1} |
Schema rules: {"type":"object","additionalProperties":false}.
RetryInfo
How long the caller must wait before it retries.
| Field | Required | Description and type |
|---|---|---|
retry_after_seconds | Yes | {"type":"integer","minimum":1,"maximum":60} |
Schema rules: {"type":"object","additionalProperties":false}.
ErrorEnvelope
The one error shape every backend response uses.
| Field | Required | Description and type |
|---|---|---|
error | Yes | {"type":"object","properties":{"code":{"type":"string","enum":["account_suspended","account_concurrency_limited","abuse_limited","ai_failure_limit_reached","ai_needs_paid_credits","already_subscribed","auth_unavailable","batch_row_limit","billing_unavailable","brand_asset_account_limit_reached","brand_asset_invalid","brand_asset_kind_invalid","brand_asset_kind_mismatch","brand_asset_limit_reached","brand_asset_too_large","brand_asset_type_unsupported","brand_data_conflict","brand_font_glyphs_exceeded","brand_font_tables_invalid","brand_image_animated","brand_image_dimensions_invalid","brand_image_pixels_exceeded","brand_kit_colours_invalid","brand_kit_conflict","brand_kit_limit","brand_kit_name_invalid","brand_kit_not_found","brand_kit_patch_empty","brand_kit_tone_invalid","brand_kit_unavailable","captcha_rejected","checkout_superseded","cross_origin_rejected","csrf_rejected","download_expired","email_already_set","gallery_template_not_found","generated_template_invalid","idempotency_conflict","image_asset_header_unsupported","image_asset_invalid","image_asset_limit","image_asset_not_found","image_asset_reference_invalid","image_asset_too_large","image_asset_type_unsupported","image_asset_unavailable","image_url_invalid","image_url_unavailable","insufficient_credits","internal_error","invalid_cursor","invalid_email","invalid_event","invalid_link","invalid_profile","invalid_request","invalid_upload","job_not_finished","key_concurrency_limited","key_limit_reached","method_not_allowed","no_billing_customer","not_found","operation_conflict","operation_limit_exceeded","operation_pending","overage_limit_reached","overage_unavailable","overloaded","playground_busy","playground_request_invalid","playground_selection_invalid","playground_session_limited","playground_unavailable","policy_version_stale","provider_unavailable","rate_limited","render_probe_busy","render_probe_failed","render_probe_not_configured","render_probe_required","render_probe_timeout","request_headers_too_large","request_too_large","resize_timeout","signed_out","spend_cap_reached","template_build_not_found","template_data_collection_limit","template_data_depth_limit","template_data_invalid","template_data_limit","template_depth_limit","template_draft_not_found","template_evaluation_error","template_invalid_filter_input","template_missing_data","template_output_limit","template_not_found","template_schema_complexity","template_schema_draft_unsupported","template_schema_invalid","template_schema_too_large","template_size_canvas_mismatch","template_size_data_overrides_too_large","template_size_duplicate_id","template_size_invalid_dimensions","template_size_invalid_id","template_size_invalid_name","template_sizes_too_large","template_sizes_too_many","template_source_limit","template_syntax_error","template_timeout","template_version_changed","template_work_limit","testimonial_busy","testimonial_invalid","testimonial_rate_limited","testimonial_unavailable","unauthorized","unsupported_media_type","webhook_limit_reached"],"description":"A fixed, machine-readable error code."},"message":{"type":"string","description":"A fixed, human-readable message."},"request_id":{"type":"string","format":"uuid","description":"The identifier this answer also carries in its x-request-id header."},"details":{"type":"array","description":"Present on a validation failure. Schema failures return at most 16 entries with bounded data paths and fixed reasons. Values from the request are never repeated.","items":{"$ref":"#/components/schemas/FieldDetail"}},"retry":{"$ref":"#/components/schemas/RetryInfo"},"plan_limit":{"$ref":"#/components/schemas/PlanLimitInfo"}},"required":["code","message","request_id"],"additionalProperties":false} — FieldDetail, RetryInfo, PlanLimitInfo |
Schema rules: {"type":"object","additionalProperties":false}.
Headers and security
XRequestId
{
"description": "The UUID that identifies this request and matches error.request_id on an error response.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
sessionCookie
{
"type": "apiKey",
"in": "cookie",
"name": "__Host-thirds_session",
"description": "A browser session. Browser writes also require the matching x-csrf-token header from GET /v1/me."
}
bearerAuth
{
"type": "http",
"scheme": "bearer",
"description": "An API key's secret, sent as \"Authorization: Bearer thirds_sk_v1_...\"."
}