Device Magic MCP by usefulapi

List the organization's forms: id, namespace (the form's unique id used for dispatching), version, description and group. GET /organizations/{org}/forms.json.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One form's definition: title and its questions/pages with identifiers and types (the identifiers are the keys inside submissions and dispatch payloads). Optionally a specific version. GET /organizations/{org}/forms/{id}.json.

{
  "type": "object",
  "properties": {
    "form_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Form id (field `id` of list_forms)."
    },
    "version": {
      "description": "Form version such as 1.03; default = the latest.",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    }
  },
  "required": [
    "form_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Submitted data of one form, newest data as stored in the form's Device Magic Database destination (it must be active on that form). Each record has form info, metadata (device, user, submitted_at, received_at, submission_id) and the answers. The reply says current_page, total_pages and total_count. Filter by from_date/to_date (yyyy-mm-dd). GET /api/forms/{id}/device_magic_database.json.

{
  "type": "object",
  "properties": {
    "form_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Form id (field `id` of list_forms)."
    },
    "from_date": {
      "description": "Only submissions from this date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "to_date": {
      "description": "Only submissions up to this date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "per_page": {
      "description": "Submissions per page, 1-100 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "page": {
      "description": "Page number, 1-based (use total_pages from the reply).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "required": [
    "form_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the organization's devices (phones, tablets, web-form users): id, identifier, owner, description, group and whether approval is pending. GET /organizations/{org}/devices.json.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One device: id, identifier, owner, description, pending_approval, groups and custom attributes. GET /organizations/{org}/devices/{id}.json.

{
  "type": "object",
  "properties": {
    "device_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Numeric device id (field `id` of list_devices)."
    }
  },
  "required": [
    "device_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the organization's groups (which devices see which forms), optionally narrowed by a name filter or by tags. GET /api/v2/organizations/{org}/groups.json.

{
  "type": "object",
  "properties": {
    "filter": {
      "description": "Group name to look for, e.g. Default (the vendor matches part of the name).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "tags": {
      "description": "Only groups having any of these tags (the vendor matches any tag).",
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 100
      }
    },
    "page": {
      "description": "Page number, 1-based (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the organization's resources (lookup tables and files used by forms): id, original filename, version, description. GET /api/resources.json.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Metadata of one resource: status, version and, for spreadsheets, its tables and columns. The file content itself is not downloaded. GET /api/resources/{id}/describe.json.

{
  "type": "object",
  "properties": {
    "resource_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Resource id (field `id` of list_resources)."
    }
  },
  "required": [
    "resource_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List where one form's submissions are sent (e-mail, Dropbox, database, ...): id, active flag, format and transport types, timestamps. GET /api/forms/{id}/destinations.json.

{
  "type": "object",
  "properties": {
    "form_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Form id (field `id` of list_forms)."
    }
  },
  "required": [
    "form_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One destination of a form. Credentials and tokens of the destination are never returned. GET /api/forms/{form_id}/destinations/{id}.json.

{
  "type": "object",
  "properties": {
    "form_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Form id."
    },
    "destination_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Destination id (field `id` of list_destinations)."
    }
  },
  "required": [
    "form_id",
    "destination_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Outstanding dispatches (prefilled forms pushed to devices and not yet completed) of the whole organization: id, form name and namespace, device, scheduled time. Dispatch is an Enterprise-plan feature. GET /api/v2/organizations/{org}/dispatches.json.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Outstanding dispatches of one device. GET /api/v2/devices/{identifier}/dispatches.json.

{
  "type": "object",
  "properties": {
    "device_identifier": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Device identifier (field `identifier` of a device, e.g. iPhone_abcdef1234567890)."
    }
  },
  "required": [
    "device_identifier"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One dispatch of a device including the values it was prefilled with. GET /api/v3/devices/{identifier}/dispatches/{id}.json?include_inputs=true.

{
  "type": "object",
  "properties": {
    "device_identifier": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Device identifier (field `identifier` of a device, e.g. iPhone_abcdef1234567890)."
    },
    "dispatch_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Dispatch id (field `id` of a dispatch list)."
    }
  },
  "required": [
    "device_identifier",
    "dispatch_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Devices and web-forms users a dispatch can be sent to (first 100 by default; use items and page for more). GET /api/v3/dispatch_authors.json.

{
  "type": "object",
  "properties": {
    "items": {
      "description": "Results per page (default 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "page": {
      "description": "Page number, 1-based.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: pushes a form, optionally prefilled, to one device where its user will see it (like assigning a job). Not idempotent: calling it twice sends two dispatches. Needs the Enterprise plan. The form is named by its namespace (list_forms); `payload` maps question identifiers (get_form) to prefilled values (subforms = nested objects, repeat groups = arrays). POST /api/v2/devices/{identifier}/dispatches.json.

{
  "type": "object",
  "properties": {
    "device_identifier": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Device identifier (field `identifier` of a device, e.g. iPhone_abcdef1234567890)."
    },
    "form_namespace": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Form namespace (field `namespace` of list_forms)."
    },
    "payload": {
      "description": "Prefilled values keyed by question identifier.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "form_name": {
      "description": "Title shown to the device user.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "form_description": {
      "description": "Description shown to the device user (Device Magic allows at most 255 characters).",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "scheduled_at": {
      "description": "When the dispatch becomes due, ISO 8601 such as 2026-11-02T09:00:00Z.",
      "type": "string",
      "minLength": 10,
      "maxLength": 40
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: you confirm the form is sent to this device now (its user sees it)."
    }
  },
  "required": [
    "device_identifier",
    "form_namespace",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: withdraws one outstanding dispatch from a device (the form disappears from the device). It cannot be undone, but the dispatch can be sent again. DELETE /api/v2/devices/{identifier}/dispatches/{id}.json.

{
  "type": "object",
  "properties": {
    "device_identifier": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Device identifier (field `identifier` of a device, e.g. iPhone_abcdef1234567890)."
    },
    "dispatch_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Dispatch id (from list_device_dispatches)."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: you confirm the dispatch is withdrawn from the device."
    }
  },
  "required": [
    "device_identifier",
    "dispatch_id",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: approves a device that is waiting for approval (pending_approval is true) so it can receive forms. Approving an approved device has no effect. POST /organizations/{org}/devices/{id}/approve.

{
  "type": "object",
  "properties": {
    "device_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Numeric device id (field `id` of list_devices)."
    }
  },
  "required": [
    "device_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}