Skip to main content
The Run Spell endpoint lets you call your spell programmatically. We have two modes you can use:
  • Wait Mode (wait: true): Will keep the connection open until the spell returns. Best for spells that run quickly (< 60s).
  • Polling Mode (wait: false): Will return a spell run ID for you to poll for results.
Wait Mode is simpler to implement, and works for most spells. Polling Mode is best for long-running spells, or if your architecture isn’t suited for handling long-running connections. To call a spell, you’ll need to enter the spell ID (found in the URL or on the spell page’s API tab) and the JSON representation of the inputs (found in the spell page’s API tab).

​
Wait Mode

To start the spell run: 
const response = await fetch('https://api-v2.respell.ai/spells/start', {
  method: 'POST',
  headers: {
    authorization: 'Bearer {{ YOUR API KEY }}',
    accept: 'application/json',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    spellId: '{{ YOUR SPELL ID }}',
    wait: true,
    inputs: {
        "search_topic": "{{ YOUR CUSTOM INPUT }}"
      },
  }),
})
The spell run results will be returned as JSON in the response body: 
{
  "outputs": {
    "search_topic": "{{ SPELL RUN OUTPUT }}"
  }
}

​
Polling Mode

To start the spell run: 
const response = await fetch('https://api-v2.respell.ai/spells/start', {
  method: 'POST',
  headers: {
    authorization: 'Bearer {{ YOUR API KEY }}',
    accept: 'application/json',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    spellId: '{{ YOUR SPELL ID }}',
    wait: false,
    inputs: {
        "search_topic": "{{ YOUR CUSTOM INPUT }}"
      },
  }),
})
The spell run ID will be returned as JSON in the response body: 
{
    "runId": {{ SPELL RUN ID }},
}
You can use the spell run ID to poll for results: 
const response = await fetch('https://api-ox4n3wkxsa-uw.a.run.app/spells/getRun', {
  method: 'GET',
  headers: {
    authorization: 'Bearer {{ YOUR API KEY }}',
    accept: 'application/json',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    runId: {{ SPELL RUN ID }},
  }),
})
The spell run results will be returned as JSON in the response body once the run is successful: 
// If the run is finished, any outputs will be returned in 'outputs'
{
  "outputs": {
    "search_topic": "{{ SPELL RUN OUTPUT }}"
  },
  "state": "success" // "success", "failure", "error", or "inProgress"
}
// If the run is inProgress, 'outputs' will be an empty object
{
  "outputs": {},
  "state": "inProgress"
}