SafetyDataSheetAPI Extraction API
Synchronous single-document SDS extraction.
Synchronous single-document SDS extraction.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/safetydatasheetapi:safetydatasheetapi-extraction-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: SafetyDataSheet Extraction API
version: 1.0.0
summary: Extract Safety Data Sheet (SDS/MSDS) PDFs into structured JSON, XML, and CSV.
description: 'SafetyDataSheetAPI converts Safety Data Sheet PDFs into normalized, 16-section compliance records
in JSON, XML, and CSV.
**Authentication.** Production extraction endpoints require an API key, sent as
`Authorization: Bearer ` or as an `X-API-Key` header. Request a key through the
self-serve signup on https://safetydatasheetapi.com/#self-serve-signup.
**Rate limits.** Extraction responses include `X-RateLimit-Remaining` and, when a limit applies,
`X-RateLimit-Reset` (Unix epoch seconds). When the limit is exceeded the API returns `429` with
error code `rate_limited`, a standard `Retry-After` header (seconds to wait), and
`retry_after_epoch_seconds` in the body.
**Errors.** Every error uses one envelope: `{"ok": false, "error": {"code": "...", "message": "..."}}`,
optionally with extra detail fields. Branch on `error.code`, which is stable; `message` is for humans.
**Async bulk jobs.** `POST /extract-sds/bulk` returns `202` with a `job_id`. Poll
`GET /extract-sds/bulk/{jobId}` or pass `callback_url` to receive a signed webhook
(`X-Webhook-Signature`). Send an `Idempotency-Key` header to make job submission safe to retry.'
termsOfService: https://safetydatasheetapi.com/terms/
license:
name: Proprietary (see Terms of Service)
url: https://safetydatasheetapi.com/terms/
contact:
name: SafetyDataSheetAPI Support
url: https://safetydatasheetapi.com/contact/
email: sales@safetydatasheetapi.com
servers:
- url: https://safetydatasheetapi.com
description: Hosted API (free sample upload, and self-serve API keys). Enterprise customers use the dedicated base URL provided at onboarding.
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: Extraction
description: Synchronous single-document SDS extraction.
paths:
/extract-sds:
post:
tags:
- Extraction
summary: Extract structured SDS data from a single PDF
description: 'Upload one SDS/MSDS PDF as `multipart/form-data` and receive the extracted record in JSON, XML,
and CSV inside one JSON response. The file must be a real PDF (signature is checked).'
operationId: extractSds
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: The SDS/MSDS PDF to extract.
language_hint:
type: string
description: Optional language hint, for example `en`, `de`, `fr`.
examples:
- en
schema_version:
type: string
description: Optional. Pins the output schema version. Only `1.0` exists; any other value returns 400 `unsupported_schema_version`.
examples:
- '1.0'
responses:
'200':
description: Extraction succeeded.
headers:
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
content:
application/json:
schema:
$ref: '#/components/schemas/ExtractionResponse'
examples:
success:
summary: Successful extraction
value:
ok: true
request_id: 2f6c1a54-7b0e-4d0a-9d52-6a1f0f3c9b11
output_formats:
- JSON
- XML
- CSV
confidence_score: 0.94
document_language: en
warnings: []
outputs:
json:
product_identification:
product_name: Acetone
supplier_name: Example Chemicals
transport_information:
un_number: UN1090
proper_shipping_name: Acetone
hazard_class: '3'
packing_group: II
xml: '<?xml version="1.0" encoding="UTF-8"?>
<sds_extraction><product_identification><product_name>Acetone</product_name></product_identification></sds_extraction>'
csv: 'field,value
product_identification.product_name,Acetone
transport_information.un_number,UN1090'
metadata:
file_name: acetone-sds.pdf
file_size_bytes: 184220
language_hint: en
document_language: en
schema_version: '1.0'
processing_ms: 8412
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'405':
$ref: '#/components/responses/MethodNotAllowed'
'413':
$ref: '#/components/responses/PayloadTooLarge'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
'502':
$ref: '#/components/responses/ProviderError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
components:
schemas:
Error:
type: object
description: Standard error envelope returned by every endpoint. Additional detail fields may be present alongside `error`.
required:
- ok
- error
properties:
ok:
type: boolean
const: false
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Stable machine-readable error code. Branch on this value.
examples:
- rate_limited
message:
type: string
description: Human-readable explanation. May change; do not parse.
request_id:
type: string
description: Present on server-side failures (5xx). Quote it when contacting support; internal detail is logged against this id and is never returned in the response.
additionalProperties: true
ExtractionResponse:
type: object
required:
- ok
- request_id
- output_formats
- confidence_score
- warnings
- outputs
properties:
ok:
type: boolean
const: true
request_id:
type: string
description: Id for this request (the Cloudflare Ray id when present, otherwise a UUID). Quote it when contacting support.
output_formats:
type: array
items:
type: string
enum:
- JSON
- XML
- CSV
confidence_score:
type: number
minimum: 0
maximum: 1
description: Extraction confidence from 0 to 1.
document_language:
type:
- string
- 'null'
description: Language the document is written in, detected from the document itself (an ISO 639-1 code such as `sv`, or a regional form such as `pt-BR`). `null` when it could not be determined. Not the same as `language_hint`, which is only the hint you sent.
examples:
- sv
billing:
type: object
description: Present when a per-customer API key is used. Failed extractions are never billed.
properties:
pages:
type: integer
description: Pages in the document.
documents_billed:
type: integer
description: Documents charged; one per 40 pages (rounded up).
cost_usd:
type: number
schema_version:
type:
- string
- 'null'
description: Version of the response schema applied to `outputs.json` (`1.0`). Also returned in `metadata.schema_version`.
examples:
- '1.0'
is_safety_data_sheet:
type:
- boolean
- 'null'
description: Whether the uploaded document looks like a safety data sheet. Present when the fixed schema is enabled for the deployment; `false` is accompanied by a warning and mostly empty fields.
warnings:
type: array
items:
type: string
outputs:
type: object
properties:
json:
type: object
additionalProperties: true
description: 'Normalized SDS record, grouped by SDS section. Top-level keys: product_identification, hazards_identification, composition, first_aid, fire_fighting, accidental_release, handling_storage, exposure_controls_ppe, physical_chemical_properties, stability_reactivity, toxicological_information, ecological_information, disposal_considerations, transport_information, regulatory_information, revision_metadata.'
xml:
type: string
description: The same record serialized as XML (root element `sds_extraction`).
csv:
type: string
description: The same record as CSV with a `field,value` header and dotted field paths such as `product_identification.product_name`.
metadata:
type: object
properties:
file_name:
type: string
file_size_bytes:
type: integer
language_hint:
type:
- string
- 'null'
description: The hint you sent, or `null` if you sent none.
document_language:
type:
- string
- 'null'
description: Same value as the top-level `document_language`.
schema_version:
type:
- string
- 'null'
processing_ms:
type: integer
description: Server-side processing time in milliseconds.
responses:
RateLimited:
description: Rate limit reached for the current window. Wait `Retry-After` seconds (or until `retry_after_epoch_seconds`), then retry.
headers:
Retry-After:
$ref: '#/components/headers/RetryAfter'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
retry_after_epoch_seconds:
type: integer
description: Unix epoch seconds after which the request may be retried.
example:
ok: false
error:
code: rate_limited
message: Upload limit reached for this time window.
retry_after_epoch_seconds: 1792800000
BadRequest:
description: Invalid input, such as a missing file, wrong content type, unsupported file type, invalid email, too many files, or an unsafe callback URL.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
ok: false
error:
code: missing_file
message: File is required in the 'file' field.
Unauthorized:
description: The API key is missing or invalid (`unauthorized`), or has been revoked (`api_key_revoked`). A suspended account returns 403 `account_suspended`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
ok: false
error:
code: unauthorized
message: Invalid or missing API key.
ServerError:
description: Extraction succeeded or was attempted but the server failed while formatting or processing the result (`output_processing_failed`). Retrying is safe.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
ok: false
error:
code: output_processing_failed
message: Extraction succeeded but formatting the response failed. Please retry.
request_id: 7ce6ebcf-dc15-410a-9e27-5ce5f3d074c9
Forbidden:
description: Request blocked, either by the IP allow/deny policy (`ip_restricted`) or by failed human verification (`verification_failed`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
ok: false
error:
code: ip_restricted
message: Your IP is not allowed for this endpoint.
reason: ip_denied
MethodNotAllowed:
description: The HTTP method is not supported on this path.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
ok: false
error:
code: method_not_allowed
message: Use POST for this endpoint.
PayloadTooLarge:
description: A file exceeds the per-file limit, or a bulk job exceeds the combined size limit (`file_too_large`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
ok: false
error:
code: file_too_large
message: File size exceeds 10 MB limit.
ServiceUnavailable:
description: The endpoint or its extraction provider is not configured (`extract_api_not_configured`, `provider_not_configured`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
ok: false
error:
code: extract_api_not_configured
message: This endpoint is not available. Please contact support.
ProviderError:
description: The upstream extraction provider failed (`provider_error`). Also returned with status `500` when the provider gave no HTTP status. Retry with exponential backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
ok: false
error:
code: provider_error
message: The extraction provider failed to process this document. Please retry.
request_id: 7ce6ebcf-dc15-410a-9e27-5ce5f3d074c9
PaymentRequired:
description: The account's prepaid credit does not cover this request (`insufficient_credit`). Buy credit in the dashboard (Billing). Nothing was processed or billed. `balance_usd`, `required_usd`, `pages` and `documents_billed` are returned beside `error`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
ok: false
error:
code: insufficient_credit
message: Not enough credit for this document. Add credit to continue.
balance_usd: 0.1
required_usd: 0.25
pages: 12
documents_billed: 1
headers:
RateLimitRemaining:
description: Requests remaining in the current rate-limit window. Present when a limit is enforced.
schema:
type: integer
minimum: 0
RateLimitReset:
description: Unix epoch seconds when the current rate-limit window resets.
schema:
type: integer
RetryAfter:
description: Seconds to wait before retrying. Sent on `429` responses.
schema:
type: integer
minimum: 1
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: 'API key sent as `Authorization: Bearer <api_key>`. Never send keys in the query string.'
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Alternative to the Bearer header. Send the same API key as `X-API-Key`.
externalDocs:
description: API documentation and quickstart
url: https://safetydatasheetapi.com/api-docs/
x-agentic-access:
version: '1.0'
summary: How autonomous agents and AI assistants can use this API safely.
authentication:
type: api_key
schemes:
- bearerAuth
- apiKeyAuth
interactive_login_required: false
obtain_key: https://safetydatasheetapi.com/#self-serve-signup
note: Agents must be given a key by a human; they cannot self-register. Self-serve accounts receive their own key; enterprise customers receive a dedicated deployment and base URL.
interfaces:
rest: https://safetydatasheetapi.com/openapi.yaml
mcp:
url: https://safetydatasheetapi.com/mcp
transport: streamable-http
authentication: bearer
manifest: https://safetydatasheetapi.com/mcp-manifest.yml
skill: https://safetydatasheetapi.com/.well-known/agent-skills/safetydatasheetapi/SKILL.md
clients: https://safetydatasheetapi.com/sdks/
side_effects:
extractSds: Consumes API quota. Creates no durable customer-visible resource.
extractSdsBulk: Consumes API quota. Creates a job record retrievable through getBulkJobStatus.
getBulkJobStatus: None. Read-only and safe to repeat.
idempotency:
operations:
- extractSdsBulk
header: Idempotency-Key
behavior: A repeat with the same key returns the existing job with idempotent_replay true.
retry_guidance:
retry_after_header: Retry-After
retry_on_status:
- 429
- 500
- 502
do_not_retry_on_status:
- 400
- 401
- 403
- 404
- 413
stable_error_field: error.code
human_review:
recommended_when: The response has non-empty warnings or a low confidence_score.
note: Extracted data is machine-generated. Do not treat it as verified compliance data without review against the source document.
rate_limits: https://safetydatasheetapi.com/api-docs/#rate-limits
data_handling: https://safetydatasheetapi.com/data-residency/