What file formats does the extract endpoint accept?

The POST /api/v1/extract endpoint accepts multipart form data with a file field. The API currently supports PDF files. An optional facility_id scopes the job to a workspace.

What does the results response contain?

Once a job status is completed, GET /api/v1/jobs/{job_id}/results returns instruments, equipment, and lines arrays. Each instrument carries its tag number, ISA type, signal class, and page number.

What webhook events are available?

Three events are available: processing.completed, processing.failed, and test.ping. Failed deliveries retry with exponential backoff, and an endpoint that keeps failing is auto-disabled and can be re-enabled from the dashboard. Every delivery is signed with an X-Tagsight-Signature header carrying a timestamp and signature; verify it before processing.

What are the API rate limits?

Submit up to 10 extract requests per minute per API key; listing is 60/min, status polling 120/min, and results 60/min. Files can be up to 250 MB per drawing (500 MB on paid plans). One credit is charged per page when the job is submitted.

API reference.

Q: How do I authenticate API requests?

All requests carry an Authorization header with a bearer token. Keys are scoped per workspace and can be revoked instantly from Dashboard, API Keys. API keys are available on every paid plan.

Q: Does Tagsight support MCP integration?

Yes. Tagsight is reachable over the Model Context Protocol, so an MCP-compatible desktop client can run extractions and pull structured results directly. See the MCP reference for setup and the tool catalogue.

REST API on every paid plan. Submit P&ID drawings, poll extraction status, and fetch structured results. Create a key from Dashboard, API Keys.

Start a workspace Get an API key

Authentication.

All requests carry an Authorization header with a bearer token. Keys are scoped per workspace and can be revoked instantly from /dashboard/api-keys.

Authorization: Bearer ts_live_...

Endpoints.

Four endpoints cover the full extraction loop. Submit a drawing, list your jobs, poll a job for status, and fetch the results when it completes.

POST/api/v1/extract

Submit a P&ID drawing for extraction. Accepts multipart form data with a file field (PDF) and an optional facility_id to scope the job to a workspace. One credit is charged per page.

Request

curl -X POST https://api.tagsight.io/api/v1/extract \
  -H "Authorization: Bearer $TS_KEY" \
  -F "file=@drawing.pdf"

Response

{
  "job": {
    "id": "4f8e2a1c9d3b",
    "status": "queued",
    "filename": "drawing.pdf",
    "page_count": 3,
    "processed_pages": 0,
    "instrument_count": 0,
    "credits_charged": 3,
    "created_at": "2026-07-19T14:02:11Z",
    "error": null
  }
}

GET/api/v1/jobs

List your jobs, newest first. Cursor-paginated via next_cursor; filter with status and limit (max 100).

Request

curl "https://api.tagsight.io/api/v1/jobs?limit=20" \
  -H "Authorization: Bearer $TS_KEY"

Response

{
  "jobs": [
    {
      "id": "4f8e2a1c9d3b",
      "status": "completed",
      "filename": "drawing.pdf",
      "page_count": 3,
      "processed_pages": 3,
      "instrument_count": 42,
      "credits_charged": 3,
      "created_at": "2026-07-19T14:02:11Z",
      "error": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/api/v1/jobs/{job_id}

Poll a job for status. Status values: queued, processing, completed, failed.

Request

curl https://api.tagsight.io/api/v1/jobs/4f8e2a1c9d3b \
  -H "Authorization: Bearer $TS_KEY"

Response

{
  "job": {
    "id": "4f8e2a1c9d3b",
    "status": "completed",
    "filename": "drawing.pdf",
    "page_count": 3,
    "processed_pages": 3,
    "instrument_count": 42,
    "credits_charged": 3,
    "created_at": "2026-07-19T14:02:11Z",
    "error": null
  }
}

GET/api/v1/jobs/{job_id}/results

Fetch structured results once status is completed. Returns instruments, equipment, and lines arrays.

Request

curl https://api.tagsight.io/api/v1/jobs/4f8e2a1c9d3b/results \
  -H "Authorization: Bearer $TS_KEY"

Response (excerpt)

{
  "job_id": "4f8e2a1c9d3b",
  "filename": "drawing.pdf",
  "page_count": 3,
  "instruments": [
    {
      "tag_number": "PT-101",
      "instrument_type": "PT",
      "signal_class": "AI",
      "description": "Feed pressure transmitter",
      "page_number": 1,
      "review": "Extracted",
      "loop_number": "101",
      "signal_type": "4-20mA",
      "system": "BPCS",
      "location": "FIELD"
    },
    {
      "tag_number": "XV-2301",
      "instrument_type": "XV",
      "signal_class": "DO",
      "description": "Feed isolation valve",
      "page_number": 1,
      "review": "Needs review",
      "loop_number": "2301",
      "signal_type": "discrete",
      "system": "BPCS",
      "location": "FIELD"
    }
  ],
  "equipment": [
    { "tag": "P-101", "equipment_type": "pump", "description": "Feed pump", "page_number": 1, "review": "Extracted" }
  ],
  "lines": [
    { "line_number": "4\"-CS-101-A1A", "nominal_size": "4 inch", "spec_code": "A1A", "service": "feed", "page_number": 1 }
  ]
}

Webhooks.

Configure endpoints at Dashboard, Webhooks. Three events are available: processing.completed, processing.failed, and test.ping. Failed deliveries retry with exponential backoff. If an endpoint continues to fail the webhook is auto-disabled and can be re-enabled from the dashboard.

Every delivery is signed with an X-Tagsight-Signature header carrying a timestamp and signature (t=<ts>,v1=<sig>), computed from the workspace webhook secret. Verify before processing:

import hashlib
import hmac
import time

# Header: X-Tagsight-Signature: t=<unix_ts>,v1=<hex_signature>
def verify_webhook(
    secret: str,
    raw_body: bytes,
    signature_header: str,
    tolerance_seconds: int = 300,
) -> bool:
    parts = dict(
        p.split("=", 1) for p in signature_header.split(",") if "=" in p
    )
    timestamp, received = parts.get("t"), parts.get("v1")
    if not timestamp or not received:
        return False
    # Reject stale deliveries (replay protection)
    if abs(time.time() - int(timestamp)) > tolerance_seconds:
        return False
    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)

Tagsight Intelligence.

Ask questions across a workspace, facility, or a single drawing and receive an answer with citations that point back to the exact tag and page. Available on Pro and Firm plans.

POST/api/v1/intelligence

Ask a question synchronously. The scope object sets the boundary: workspace, facility, artifact (a single drawing), or selection. The response returns answer_md and citations that link back to the exact tag and page.

Request

curl -X POST https://api.tagsight.io/api/v1/intelligence \
  -H "Authorization: Bearer $TS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": { "level": "facility", "facility_id": "8f3a1c9d2e4b" },
    "question": "Which pressure transmitters are missing a signal class?"
  }'

Response (excerpt)

{
  "answer_md": "Two pressure transmitters are missing a signal class: ...",
  "citations": [
    {
      "label": "PT-101",
      "kind": "instrument",
      "tag_number": "PT-101",
      "artifact_id": "4f8e2a1c9d3b",
      "page": 1
    }
  ],
  "actions": [],
  "mode": "freeform",
  "scope_used": { "level": "facility", "facility_id": "8f3a1c9d2e4b" },
  "input_tokens": 1840,
  "output_tokens": 214,
  "total_cost_usd": 0.019,
  "turns_used": 1,
  "request_id": "req_7c2f9a1e",
  "contract_version": 1
}

Longer questions can run asynchronously. POST /api/v1/intelligence/jobs submits a job; poll it with GET /api/v1/intelligence/jobs/{id}, cancel with DELETE /api/v1/intelligence/jobs/{id}, or pass a webhook_url to be notified on completion. GET /api/v1/intelligence/playbooks returns scope-aware starter questions. Firm plans can export a full GET /api/v1/audit-log of every query.

Limits, error codes.

Limits

Rate limits: Submit 10/min; list 60/min; status 120/min; results 60/min, per API key.
File size: Up to 250 MB per drawing; 500 MB on paid plans.
Credits: One credit per page, charged when the job is submitted.

Errors

400: Malformed request. Missing file, a non-PDF upload, an invalid parameter, or a PDF that could not be read.
401: Missing or invalid API key.
402: Insufficient credits.
403: Not permitted. Email unverified, mode not enabled, facility not accessible, or the request came from an IP outside the key's allowlist.
404: Job or results not found.
413: File exceeds the size limit for your plan.
429: Rate limit exceeded. Retry after the window resets.
500: Processing error. The job is not charged if it fails before processing begins.
503: Extraction temporarily unavailable. Retry shortly.

MCP.

Tagsight is also reachable over the Model Context Protocol, so an MCP-compatible desktop client can run extractions and pull structured results without writing HTTP calls. See the MCP reference for setup and the tool catalogue.

Get an API key.

API keys are available on every paid plan. Create one from the dashboard, or talk to us about an Enterprise key set.

Get an API key Pricing

Endpoints.

Four endpoints cover the full extraction loop. Submit a drawing, list your jobs, poll a job for status, and fetch the results when it completes.

POST/api/v1/extract

Submit a P&ID drawing for extraction. Accepts multipart form data with a file field (PDF) and an optional facility_id to scope the job to a workspace. One credit is charged per page.

Request

curl -X POST https://api.tagsight.io/api/v1/extract \
  -H "Authorization: Bearer $TS_KEY" \
  -F "file=@drawing.pdf"

Response

{
  "job": {
    "id": "4f8e2a1c9d3b",
    "status": "queued",
    "filename": "drawing.pdf",
    "page_count": 3,
    "processed_pages": 0,
    "instrument_count": 0,
    "credits_charged": 3,
    "created_at": "2026-07-19T14:02:11Z",
    "error": null
  }
}

GET/api/v1/jobs

List your jobs, newest first. Cursor-paginated via next_cursor; filter with status and limit (max 100).

Request

curl "https://api.tagsight.io/api/v1/jobs?limit=20" \
  -H "Authorization: Bearer $TS_KEY"

Response

{
  "jobs": [
    {
      "id": "4f8e2a1c9d3b",
      "status": "completed",
      "filename": "drawing.pdf",
      "page_count": 3,
      "processed_pages": 3,
      "instrument_count": 42,
      "credits_charged": 3,
      "created_at": "2026-07-19T14:02:11Z",
      "error": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/api/v1/jobs/{job_id}

Poll a job for status. Status values: queued, processing, completed, failed.

Request

curl https://api.tagsight.io/api/v1/jobs/4f8e2a1c9d3b \
  -H "Authorization: Bearer $TS_KEY"

Response

{
  "job": {
    "id": "4f8e2a1c9d3b",
    "status": "completed",
    "filename": "drawing.pdf",
    "page_count": 3,
    "processed_pages": 3,
    "instrument_count": 42,
    "credits_charged": 3,
    "created_at": "2026-07-19T14:02:11Z",
    "error": null
  }
}

GET/api/v1/jobs/{job_id}/results

Fetch structured results once status is completed. Returns instruments, equipment, and lines arrays.

Request

curl https://api.tagsight.io/api/v1/jobs/4f8e2a1c9d3b/results \
  -H "Authorization: Bearer $TS_KEY"

Response (excerpt)

{
  "job_id": "4f8e2a1c9d3b",
  "filename": "drawing.pdf",
  "page_count": 3,
  "instruments": [
    {
      "tag_number": "PT-101",
      "instrument_type": "PT",
      "signal_class": "AI",
      "description": "Feed pressure transmitter",
      "page_number": 1,
      "review": "Extracted",
      "loop_number": "101",
      "signal_type": "4-20mA",
      "system": "BPCS",
      "location": "FIELD"
    },
    {
      "tag_number": "XV-2301",
      "instrument_type": "XV",
      "signal_class": "DO",
      "description": "Feed isolation valve",
      "page_number": 1,
      "review": "Needs review",
      "loop_number": "2301",
      "signal_type": "discrete",
      "system": "BPCS",
      "location": "FIELD"
    }
  ],
  "equipment": [
    { "tag": "P-101", "equipment_type": "pump", "description": "Feed pump", "page_number": 1, "review": "Extracted" }
  ],
  "lines": [
    { "line_number": "4\"-CS-101-A1A", "nominal_size": "4 inch", "spec_code": "A1A", "service": "feed", "page_number": 1 }
  ]
}

Webhooks.

Every delivery is signed with an X-Tagsight-Signature header carrying a timestamp and signature (t=<ts>,v1=<sig>), computed from the workspace webhook secret. Verify before processing:

import hashlib import hmac import time # Header: X-Tagsight-Signature: t=<unix_ts>,v1=<hex_signature> def verify_webhook( secret: str, raw_body: bytes, signature_header: str, tolerance_seconds: int = 300, ) -> bool: parts = dict( p.split("=", 1) for p in signature_header.split(",") if "=" in p ) timestamp, received = parts.get("t"), parts.get("v1") if not timestamp or not received: return False # Reject stale deliveries (replay protection) if abs(time.time() - int(timestamp)) > tolerance_seconds: return False signed = f"{timestamp}.".encode() + raw_body expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, received)

Tagsight Intelligence.

Ask questions across a workspace, facility, or a single drawing and receive an answer with citations that point back to the exact tag and page. Available on Pro and Firm plans.

POST/api/v1/intelligence

Request

curl -X POST https://api.tagsight.io/api/v1/intelligence \
  -H "Authorization: Bearer $TS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": { "level": "facility", "facility_id": "8f3a1c9d2e4b" },
    "question": "Which pressure transmitters are missing a signal class?"
  }'

Response (excerpt)

{
  "answer_md": "Two pressure transmitters are missing a signal class: ...",
  "citations": [
    {
      "label": "PT-101",
      "kind": "instrument",
      "tag_number": "PT-101",
      "artifact_id": "4f8e2a1c9d3b",
      "page": 1
    }
  ],
  "actions": [],
  "mode": "freeform",
  "scope_used": { "level": "facility", "facility_id": "8f3a1c9d2e4b" },
  "input_tokens": 1840,
  "output_tokens": 214,
  "total_cost_usd": 0.019,
  "turns_used": 1,
  "request_id": "req_7c2f9a1e",
  "contract_version": 1
}

Limits, error codes.

Limits

Rate limits: Submit 10/min; list 60/min; status 120/min; results 60/min, per API key.
File size: Up to 250 MB per drawing; 500 MB on paid plans.
Credits: One credit per page, charged when the job is submitted.

Errors

400: Malformed request. Missing file, a non-PDF upload, an invalid parameter, or a PDF that could not be read.
401: Missing or invalid API key.
402: Insufficient credits.
403: Not permitted. Email unverified, mode not enabled, facility not accessible, or the request came from an IP outside the key's allowlist.
404: Job or results not found.
413: File exceeds the size limit for your plan.
429: Rate limit exceeded. Retry after the window resets.
500: Processing error. The job is not charged if it fails before processing begins.
503: Extraction temporarily unavailable. Retry shortly.