Skip to main content
POST
/
v1
/
ai
/
apps
/
{app-id}
/
run
Apps - Run a workflow app
curl --request POST \
  --url https://api.magnific.com/v1/ai/apps/{app-id}/run \
  --header 'Content-Type: application/json' \
  --header 'x-magnific-api-key: <api-key>' \
  --data '
{
  "inputs": {
    "input-4050c3f3-8a26-4953-97a8-cb97bceb4816-1": "car in the forest"
  },
  "webhook": "https://www.example.com/webhook"
}
'
{
  "status": "running",
  "workflow_run_identifier": "vCrK3Aa47y"
}

Authorizations

​
x-magnific-api-key
string
header
required

Your Magnific API key. Required for authentication. Learn how to obtain an API key

Path Parameters

​
app-id
string
required

Short unique identifier (sqid) of the workflow app to execute. Discover app identifiers via GET /v1/ai/apps.

Example:

"uqzQLDr2Aw"

Body

application/json
​
inputs
object
required

Map of input id (UUID) to value. The keys of this object must match the id fields from the app's inputs array.

Value types by input type:

  • creation (image/media): URL string, base64-encoded string, or existing creation sqid
  • text: Plain text string
  • number: Numeric value
  • select: Value from allowed options
​
webhook
string<uri>

Optional callback URL that receives status notifications during execution. The webhook receives POST requests with the event payload (see webhook event schema). Events are sent when the run starts (initialized) and when it finishes (finished or failed).

Example:

"https://www.example.com/webhook"

Response

Accepted - Workflow execution started. Use the webhook to receive results.

​
status
enum<string>
required

Current execution status.

Available options:
running
Example:

"running"

​
workflow_run_identifier
string
required

Unique identifier for this workflow execution run. Matches the run_id in webhook events.

Example:

"vCrK3Aa47y"