Documentation

API

GraphQL API Reference

Schema Types

Project

graphql

type Project {
  id: ID!
  name: String!
  ownerId: String!
  createdAt: DateTime!
  assets: [Asset!]!
  forms: [Form!]!
}

Asset

graphql

type Asset {
  id: ID!
  projectId: ID!
  type: AssetType!
  url: String!
  width: Int
  height: Int
  createdAt: DateTime!
}

enum AssetType {
  IMAGE
  PDF
}

Form

graphql

type Form {
  id: ID!
  projectId: ID!
  name: String!
  currentVersion: FormVersion
  versions: [FormVersion!]!
  createdAt: DateTime!
}

FormVersion

graphql

type FormVersion {
  id: ID!
  formId: ID!
  json: String!
  source: FormSource!
  assetId: ID
  createdAt: DateTime!
  createdBy: String!
}

enum FormSource {
  MANUAL
  IMPORT
}

ConversionJob

graphql

type ConversionJob {
  id: ID!
  projectId: ID!
  assetId: ID!
  status: ConversionStatus!
  progress: Int
  resultFormId: ID
  error: String
  createdAt: DateTime!
  updatedAt: DateTime!
}

enum ConversionStatus {
  QUEUED
  PROCESSING
  COMPLETE
  FAILED
}

PdfExportResult

graphql

type PdfExportResult {
  url: String!
  sizeBytes: Int!
}

ExportPdfOptions

graphql

input ExportPdfOptions {
  paperSize: String
  includeGrid: Boolean
}

Queries

projects

List all projects for the current user.

graphql

query {
  projects {
    id
    name
    createdAt
  }
}

Example response:

json

{
  "data": {
    "projects": [
      {
        "id": "proj_001",
        "name": "Hospital Forms",
        "createdAt": "2025-06-01T10:00:00Z"
      },
      {
        "id": "proj_002",
        "name": "HR Onboarding",
        "createdAt": "2025-06-15T14:30:00Z"
      }
    ]
  }
}

project(id)

Get a single project with its assets and forms.

graphql

query {
  project(id: "proj_001") {
    id
    name
    assets {
      id
      type
      url
      createdAt
    }
    forms {
      id
      name
      currentVersion {
        id
        createdAt
        source
      }
    }
  }
}

Example response:

json

{
  "data": {
    "project": {
      "id": "proj_001",
      "name": "Hospital Forms",
      "assets": [
        {
          "id": "asset_001",
          "type": "IMAGE",
          "url": "/uploads/proj_001/scan_intake_form.png",
          "createdAt": "2025-06-01T10:05:00Z"
        }
      ],
      "forms": [
        {
          "id": "form_001",
          "name": "Patient Intake Form",
          "currentVersion": {
            "id": "fv_003",
            "createdAt": "2025-06-02T09:15:00Z",
            "source": "MANUAL"
          }
        }
      ]
    }
  }
}

form(id)

Get a form with its current version JSON and version history.

graphql

query {
  form(id: "form_001") {
    id
    name
    currentVersion {
      id
      json
      source
      createdAt
    }
    versions {
      id
      createdAt
      source
    }
  }
}

Example response:

json

{
  "data": {
    "form": {
      "id": "form_001",
      "name": "Patient Intake Form",
      "currentVersion": {
        "id": "fv_003",
        "json": "{\"schemaVersion\":\"1.0\",\"doc\":{\"id\":\"form_001\",\"name\":\"Patient Intake Form\",\"pages\":[...]}}",
        "source": "MANUAL",
        "createdAt": "2025-06-02T09:15:00Z"
      },
      "versions": [
        { "id": "fv_001", "createdAt": "2025-06-01T11:00:00Z", "source": "IMPORT" },
        { "id": "fv_002", "createdAt": "2025-06-01T15:30:00Z", "source": "MANUAL" },
        { "id": "fv_003", "createdAt": "2025-06-02T09:15:00Z", "source": "MANUAL" }
      ]
    }
  }
}

conversionStatus(jobId)

Poll the status of an AI conversion job.

graphql

query {
  conversionStatus(jobId: "job_001") {
    id
    status
    progress
    resultFormId
    error
  }
}

Example response (in progress):

json

{
  "data": {
    "conversionStatus": {
      "id": "job_001",
      "status": "PROCESSING",
      "progress": 60,
      "resultFormId": null,
      "error": null
    }
  }
}

Example response (complete):

json

{
  "data": {
    "conversionStatus": {
      "id": "job_001",
      "status": "COMPLETE",
      "progress": 100,
      "resultFormId": "form_002",
      "error": null
    }
  }
}

Mutations

createProject(name)

Create a new project.

graphql

mutation {
  createProject(name: "Hospital Forms") {
    id
    name
    createdAt
  }
}

Example response:

json

{
  "data": {
    "createProject": {
      "id": "proj_003",
      "name": "Hospital Forms",
      "createdAt": "2025-07-01T08:00:00Z"
    }
  }
}

deleteProject(id)

Delete a project and all its associated assets and forms.

graphql

mutation {
  deleteProject(id: "proj_003")
}

Example response:

json

{
  "data": {
    "deleteProject": true
  }
}

uploadAsset(projectId, file)

Upload an image or PDF asset to a project. The file argument uses the GraphQL multipart upload specification.

graphql

mutation($file: Upload!) {
  uploadAsset(projectId: "proj_001", file: $file) {
    id
    type
    url
    width
    height
    createdAt
  }
}

Example response:

json

{
  "data": {
    "uploadAsset": {
      "id": "asset_002",
      "type": "IMAGE",
      "url": "/uploads/proj_001/form_scan.png",
      "width": 2480,
      "height": 3508,
      "createdAt": "2025-07-01T08:05:00Z"
    }
  }
}

startConversion(projectId, assetId)

Start an AI conversion job to convert an uploaded asset into a form document.

graphql

mutation {
  startConversion(projectId: "proj_001", assetId: "asset_002") {
    id
    status
    createdAt
  }
}

Example response:

json

{
  "data": {
    "startConversion": {
      "id": "job_002",
      "status": "QUEUED",
      "createdAt": "2025-07-01T08:06:00Z"
    }
  }
}

createForm(projectId, name)

Create a new empty form in a project.

graphql

mutation {
  createForm(projectId: "proj_001", name: "Discharge Summary") {
    id
    name
    createdAt
  }
}

Example response:

json

{
  "data": {
    "createForm": {
      "id": "form_003",
      "name": "Discharge Summary",
      "createdAt": "2025-07-01T08:10:00Z"
    }
  }
}

saveForm(formId, json)

Save a new version of a form. The json argument is the full FormDocument JSON string.

graphql

mutation($json: String!) {
  saveForm(formId: "form_003", json: $json) {
    id
    createdAt
    source
  }
}

Variables:

json

{
  "json": "{\"schemaVersion\":\"1.0\",\"doc\":{\"id\":\"form_003\",\"name\":\"Discharge Summary\",\"pages\":[{\"id\":\"page_1\",\"size\":{\"unit\":\"mm\",\"width\":210,\"height\":297},\"elements\":[]}]}}"
}

Example response:

json

{
  "data": {
    "saveForm": {
      "id": "fv_010",
      "createdAt": "2025-07-01T08:15:00Z",
      "source": "MANUAL"
    }
  }
}

exportPdf(formId, options)

Generate a PDF from a form and return a download URL.

graphql

mutation {
  exportPdf(formId: "form_001", options: { paperSize: "A4", includeGrid: false }) {
    url
    sizeBytes
  }
}

Example response:

json

{
  "data": {
    "exportPdf": {
      "url": "/exports/form_001_20250701.pdf",
      "sizeBytes": 145832
    }
  }
}

Error Handling

All errors follow the standard GraphQL error format:

json

{
  "errors": [
    {
      "message": "project not found",
      "path": ["project"],
      "extensions": {
        "code": "NOT_FOUND"
      }
    }
  ]
}

Error Codes

Code	Description
`NOT_FOUND`	The requested resource does not exist.
`VALIDATION_ERROR`	Input validation failed.
`UPLOAD_TOO_LARGE`	Uploaded file exceeds the size limit.
`CONVERSION_FAILED`	AI conversion job failed.
`INTERNAL_ERROR`	Unexpected server error.