Create a run

POST /v1/agents/runs: start a Mangrove run from a question, a URL or an uploaded file.

POST

Authentication

All requests require an API key passed as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Endpoint

POST https://api.greenpt.ai/v1/agents/runs

Two ways to start a run:

JSON — a question, plus documentUrl or audioUrl when the question is about something at a URL.
multipart/form-data — a question plus a file. An image goes straight to the vision model, a recording is transcribed, and anything else is converted to text. The run answers from the file's content either way, so no documentUrl or audioUrl is needed for a local file.

JSON body

Field	Type	Required	Description
`question`	string	Yes	What you want Mangrove to do.
`documentUrl`	string (URL)	No	A document or image URL to analyze.
`audioUrl`	string (URL)	No	A meeting recording URL to transcribe.
`greenShiftWindowHours`	integer, 1–24	No	Hours the run may start late so it runs on cleaner electricity. See Running when the grid is cleanest.

multipart/form-data fields

Field	Type	Required	Description
`question`	string	Yes	What you want Mangrove to do.
`file`	binary	Yes	An image, a recording, or a document. The extension decides which — see below.

The extension decides how a file is read, and each kind carries its own size limit. A file over its limit is rejected with 413 before any work starts.

Kind	Extensions	Limit
Image	`.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`	10 MB
Recording	`.mp3`, `.m4a`, `.wav`, `.ogg`, `.opus`, `.flac`, `.aac`, `.webm`, `.mp4`	250 MB
Document	PDF, DOCX, and the other formats the Documents API accepts	50 MB

Response

{ "agentId": "3fa2b1e4-8c5d-4a2e-9f1b-7d6e2c9a91cd", "status": "queued" }

A run created with greenShiftWindowHours also carries a greenShift object (Running when the grid is cleanest).

Example: ask a question

curl -X POST https://api.greenpt.ai/v1/agents/runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "question": "What does GreenPT offer?"
  }'

const response = await fetch('https://api.greenpt.ai/v1/agents/runs', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer YOUR_API_KEY',
  },
  body: JSON.stringify({ question: 'What does GreenPT offer?' }),
});

const { agentId } = await response.json();
console.log(agentId);

import requests

response = requests.post(
    "https://api.greenpt.ai/v1/agents/runs",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"question": "What does GreenPT offer?"},
)

agent_id = response.json()["agentId"]
print(agent_id)

Example: analyze a document or image by URL

curl -X POST https://api.greenpt.ai/v1/agents/runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "question": "Summarize the key findings",
    "documentUrl": "https://example.com/report.pdf"
  }'

const response = await fetch('https://api.greenpt.ai/v1/agents/runs', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer YOUR_API_KEY',
  },
  body: JSON.stringify({
    question: 'Summarize the key findings',
    documentUrl: 'https://example.com/report.pdf',
  }),
});

const { agentId } = await response.json();
console.log(agentId);

import requests

response = requests.post(
    "https://api.greenpt.ai/v1/agents/runs",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "question": "Summarize the key findings",
        "documentUrl": "https://example.com/report.pdf",
    },
)

agent_id = response.json()["agentId"]
print(agent_id)

Example: analyze a meeting recording

curl -X POST https://api.greenpt.ai/v1/agents/runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "question": "What were the decisions and action items?",
    "audioUrl": "https://example.com/standup.mp3"
  }'

const response = await fetch('https://api.greenpt.ai/v1/agents/runs', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer YOUR_API_KEY',
  },
  body: JSON.stringify({
    question: 'What were the decisions and action items?',
    audioUrl: 'https://example.com/standup.mp3',
  }),
});

const { agentId } = await response.json();
console.log(agentId);

import requests

response = requests.post(
    "https://api.greenpt.ai/v1/agents/runs",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "question": "What were the decisions and action items?",
        "audioUrl": "https://example.com/standup.mp3",
    },
)

agent_id = response.json()["agentId"]
print(agent_id)

Example: upload a file directly

curl -X POST https://api.greenpt.ai/v1/agents/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "question=What does this chart show?" \
  -F "file=@chart.png"

import fs from 'node:fs';

const form = new FormData();
form.append('question', 'What does this chart show?');
form.append('file', new Blob([fs.readFileSync('chart.png')]), 'chart.png');

const response = await fetch('https://api.greenpt.ai/v1/agents/runs', {
  method: 'POST',
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
  body: form,
});

const { agentId } = await response.json();
console.log(agentId);

import requests

url = "https://api.greenpt.ai/v1/agents/runs"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {"question": "What does this chart show?"}

with open("chart.png", "rb") as f:
    files = {"file": ("chart.png", f)}
    response = requests.post(url, headers=headers, data=data, files=files)

agent_id = response.json()["agentId"]
print(agent_id)

On this page