Open API Specification (1.1)

Submit a document for processing. The file is sent as a base64 string in data.attributes.document, data.attributes.request.entities selects what to extract from it, and the optional data.attributes.request.format selects how results are serialised (json or fhir).

This is a stateless submit-and-respond operation: nothing is persisted, and the outcome is delivered through the event emitted to the orchestrator (see GET /api/requests/{id}). For raw file bytes instead of base64, use POST /api/upload_document.

curl -X POST https://{organisation}.platform.dyad.ai/api/requests \
  -H "Authorization: Bearer $EDGE_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "request",
      "attributes": {
        "document": "JVBERi0xLjQKJUVPRg==",
        "request": { "entities": ["slots"] }
      }
    }
  }'

Example response — 201 Created

{
  "data": {
    "attributes": {
      "document": "JVBERi0xLjQKJUVPRg==",
      "request": {
        "entities": [
          "slots"
        ],
        "format": "json"
      }
    },
    "id": "1f0a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8",
    "type": "request"
  }
}

Work in progress

Submit raw text for processing instead of a document. The text is sent in data.attributes.text; data.attributes.request is identical to POST /api/requests — entities, plus the optional format. Processing, the event emitted to the orchestrator, and result retrieval via GET /api/requests/{id} are the same as for a document submission.

Until this is available the endpoint responds 404 Not Found.

curl -X POST https://{organisation}.platform.dyad.ai/api/requests/text \
  -H "Authorization: Bearer $EDGE_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "request",
      "attributes": {
        "text": "Patient: Jane Doe. Clinic date: 17 Feb 2023.",
        "request": { "entities": ["slots"], "format": "json" }
      }
    }
  }'

Example response — 201 Created

{
  "data": {
    "attributes": {
      "request": {
        "entities": [
          "slots"
        ],
        "format": "json"
      },
      "text": "Patient: Jane Doe. Clinic date: 17 Feb 2023."
    },
    "id": "1f0a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8",
    "type": "request"
  }
}

Work in progress The response body for this endpoint is not finalised: the schema shown here is a placeholder and will change.

Once available, GET /api/requests/{id} will return the current state of the request identified by id — either its processing status (for example processing, succeeded, failed) while work is still in progress, or the extracted results once they are ready. The exact result shape is still being defined and depends on the entities and format requested at submission time; with format: fhir the results are returned as an HL7 FHIR R4 Bundle. The id may come from POST /api/requests, POST /api/upload_document, POST /api/requests/text, or a document within a batch.

Until then this endpoint responds 404 Not Found for every id.

curl https://{organisation}.platform.dyad.ai/api/requests/3f2a9c7e-1b4d-4e8a-9c2f-7a1e5d6b3c40 \
  -H "Authorization: Bearer $EDGE_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example response — still processing

{
  "data": {
    "attributes": {
      "status": "processing"
    },
    "id": "3f2a9c7e-1b4d-4e8a-9c2f-7a1e5d6b3c40",
    "type": "request"
  }
}

Example response — processed (2 slots shown)

{
  "data": {
    "attributes": {
      "results": {
        "slots": [
          {
            "bboxes": [
              {
                "height": 0.009692132269099207,
                "left_x": 0.5042355788624445,
                "page_index": 1,
                "top_y": 0.2913340935005701,
                "width": 0.06696248487293266
              },
              {
                "height": 0.009692132269099207,
                "left_x": 0.7301331181928197,
                "page_index": 1,
                "top_y": 0.2913340935005701,
                "width": 0.021379588543767647
              }
            ],
            "concept_id": null,
            "date": null,
            "entity_type": null,
            "explanation": "AI predicted slot value",
            "extra_info": null,
            "laterality": null,
            "problem_resolution_status": null,
            "restriction_name": null,
            "slot_id": "97b16e36-f647-4f19-bcec-7daac8a29b90",
            "snomed_code": null,
            "snomed_term": null,
            "table": "requests_tasks",
            "text": "Referrals No",
            "units": null,
            "value": null
          },
          {
            "bboxes": [
              {
                "height": 0.009407069555302166,
                "left_x": 0.2779346510689794,
                "page_index": 0,
                "top_y": 0.515678449258837,
                "width": 0.06655909640984267
              }
            ],
            "concept_id": "9663501000001101",
            "date": "2026-09-04",
            "entity_type": "medication",
            "explanation": "AI predicted slot value",
            "extra_info": null,
            "laterality": null,
            "problem_resolution_status": null,
            "restriction_name": null,
            "slot_id": "59a05416-e091-4f66-8ef8-dd12a18d2130",
            "snomed_code": "9663501000001101",
            "snomed_term": "Entonox",
            "table": "medication",
            "text": "Entonox",
            "units": null,
            "value": false
          }
        ]
      },
      "status": "succeeded"
    },
    "id": "3f2a9c7e-1b4d-4e8a-9c2f-7a1e5d6b3c40",
    "type": "request"
  }
}

Submit a document as raw file bytes via multipart/form-data, for callers who would rather not base64-encode. The file goes in the document part and the JSON-encoded request metadata in the request part. Processing and result retrieval via GET /api/requests/{id} are identical to POST /api/requests.

curl -X POST https://{organisation}.platform.dyad.ai/api/upload_document \
  -H "Authorization: Bearer $EDGE_API_TOKEN" \
  -F "document=@referral.pdf" \
  -F 'request={"entities":["slots"],"format":"json"}'

Example response — 201 Created

{
  "document": "JVBERi0xLjQKJUVPRg==",
  "id": "1f0a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8",
  "request": {
    "entities": [
      "slots"
    ],
    "format": "json"
  }
}

Example error — 400 Bad Request

{
  "errors": [
    {
      "detail": "The `request` part must be valid JSON",
      "status": "400",
      "title": "Invalid request"
    }
  ]
}

Work in progress

Submit many documents in one call by pointing Core Platform at a location in an object-storage bucket it has been granted read access to. data.attributes.request is applied to every document in the batch; data.attributes.source names the bucket and either a prefix to enumerate or an explicit list of keys.

The call returns 201 Created with a batch id. Poll GET /api/requests/batch/{id} for progress and the per-document request ids, then retrieve each document with GET /api/requests/{id} as normal.

Until this is available the endpoint responds 404 Not Found.

curl -X POST https://{organisation}.platform.dyad.ai/api/requests/batch \
  -H "Authorization: Bearer $EDGE_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "request-batch",
      "attributes": {
        "request": { "entities": ["slots"], "format": "json" },
        "source": { "bucket": "acme-inbound", "prefix": "referrals/2023-02/" }
      }
    }
  }'

Example response — 201 Created

{
  "data": {
    "attributes": {
      "request": {
        "entities": [
          "slots"
        ],
        "format": "json"
      },
      "source": {
        "bucket": "acme-inbound",
        "prefix": "referrals/2023-02/"
      },
      "status": "pending"
    },
    "id": "b1a2c3d4-0000-4000-8000-000000000001",
    "type": "request-batch"
  }
}

Work in progress

Return the state of the batch identified by id: its overall status, totals, and a documents array pairing each source object key with its per-document request id and status. Individual documents are retrieved with GET /api/requests/{id}.

Until this is available the endpoint responds 404 Not Found for every id.

curl https://{organisation}.platform.dyad.ai/api/requests/batch/b1a2c3d4-0000-4000-8000-000000000001 \
  -H "Authorization: Bearer $EDGE_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example response — 200 OK

{
  "data": {
    "attributes": {
      "documents": [
        {
          "id": "3f2a9c7e-1b4d-4e8a-9c2f-7a1e5d6b3c40",
          "key": "referrals/2023-02/0001.pdf",
          "status": "succeeded"
        },
        {
          "id": "5c6d7e8f-2a3b-4c5d-9e0f-1a2b3c4d5e6f",
          "key": "referrals/2023-02/0002.pdf",
          "status": "succeeded"
        },
        {
          "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
          "key": "referrals/2023-02/0003.pdf",
          "status": "pending"
        }
      ],
      "request": {
        "entities": [
          "slots"
        ],
        "format": "json"
      },
      "source": {
        "bucket": "acme-inbound",
        "prefix": "referrals/2023-02/"
      },
      "status": "processing",
      "totals": {
        "documents": 3,
        "failed": 0,
        "pending": 1,
        "succeeded": 2
      }
    },
    "id": "b1a2c3d4-0000-4000-8000-000000000001",
    "type": "request-batch"
  }
}

Work in progress

Register an HTTPS url to be called for the batch identified by id. By default only batch.completed / batch.failed are delivered; add batch.document.succeeded / batch.document.failed to events to also be notified per document. Optionally supply a secret for callback signing. Returns 201 Created with a subscription id.

The shape of the callback Core Platform sends is documented under Callbacks below.

Until this is available the endpoint responds 404 Not Found for every id.

curl -X POST https://{organisation}.platform.dyad.ai/api/requests/batch/b1a2c3d4-0000-4000-8000-000000000001/notifications \
  -H "Authorization: Bearer $EDGE_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "notification-subscription",
      "attributes": {
        "url": "https://acme.example.com/hooks/core-platform",
        "events": ["batch.completed", "batch.failed"]
      }
    }
  }'

Example response — 201 Created

{
  "data": {
    "attributes": {
      "events": [
        "request.succeeded",
        "request.failed"
      ],
      "url": "https://acme.example.com/hooks/core-platform"
    },
    "id": "ns_7b2c\u2026",
    "type": "notification-subscription"
  }
}

Work in progress

Register an HTTPS url to be called when the request identified by id reaches a terminal state (succeeded or failed). Optionally narrow delivery with events and supply a secret for callback signing. Returns 201 Created with a subscription id.

The shape of the callback Core Platform sends is documented under Callbacks below.

Until this is available the endpoint responds 404 Not Found for every id.

curl -X POST https://{organisation}.platform.dyad.ai/api/requests/3f2a9c7e-1b4d-4e8a-9c2f-7a1e5d6b3c40/notifications \
  -H "Authorization: Bearer $EDGE_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "notification-subscription",
      "attributes": {
        "url": "https://acme.example.com/hooks/core-platform",
        "events": ["request.succeeded", "request.failed"]
      }
    }
  }'

Example response — 201 Created

{
  "data": {
    "attributes": {
      "events": [
        "request.succeeded",
        "request.failed"
      ],
      "url": "https://acme.example.com/hooks/core-platform"
    },
    "id": "ns_7b2c\u2026",
    "type": "notification-subscription"
  }
}