SafetyDataSheetAPI Extraction API

Synchronous single-document SDS extraction.

GitHub OpenAPI

Operations 1

POST /extract-sds Extract structured SDS data from a single PDF #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/safetydatasheetapi:safetydatasheetapi-extraction-api"
All apis
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.

Get an API 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 Specification

safetydatasheetapi-extraction-api-openapi.yml Raw ↑
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/