Foreman AI icon Foreman AI

ForemanAI API

Contractor-grade intelligence via API.

Bring ForemanAI’s sheet-aware reasoning into your internal dashboards, ERPs, or ConTech products. Every response cites the source sheet, callout, and condition summary so your teams can trust the output.

Base URL

https://api.foremanai.co

Auth

Bearer token

Formats

JSON in / JSON out

Four steps to wire in ForemanAI.

  1. Create an API key

    Contact the ForemanAI team for a scoped token tied to your workspace.

  2. Upload or reference a plan

    Use the web app upload or the plan-files endpoint to register sheets.

  3. Submit an analysis job

    POST to /api/v1/plan-analyses with the modes (conflicts, rfis, schedule, metadata).

  4. Consume the results

    Poll the /api/v1/plan-analyses/<id> resource or subscribe to webhooks for completion events.

Bearer tokens with workspace scopes.

Include the header Authorization: Bearer <token> in every request. Tokens map to a workspace and can be limited to read-only, plan submission, or admin scopes.

  • Environment separation · Sandbox and production tokens are issued separately.
  • IP and org controls · Optional allowlists keep access limited to your network.
  • Rotation cadence · Rotate every 60 days or on-demand via the admin console.

Choose the workflow that fits your crews.

Plan analyses

Kick off full sheet reviews

Use when you want conflicts, RFIs, schedule checks, and metadata in a single pass.

  • plan_id from the uploaded set
  • modes array: conflicts, rfis, schedule, metadata
  • Optional notes to direct ForemanAI toward areas of concern

Inline questions

Ask about a specific sheet

Route quick Q&A to the /api/v1/plan-questions endpoint when you only need a citation-backed answer.

  • Send question, sheet_hint, and optional discipline
  • Responses cite the sheet, viewport, and callout used
  • Great for embedding in field or PM dashboards

Bulk sync

Mirror the vault in your system

Use plan-files plus pagination on conflicts to hydrate your BI tools or compliance archives.

  • All endpoints return deterministic IDs for delta syncing
  • Webhooks notify you when new conflicts exceed thresholds
  • Supports nightly or hourly ETL without rate pain

Drop-in snippets for the common stack.

Plan analysis submission

POST /api/v1/plan-analyses
Authorization: Bearer <token>
Content-Type: application/json
{
    "plan_id": "PRJ-2094",
    "modes": ["conflicts", "rfis", "schedule"],
    "notes": "Focus on Level 3 mechanical rooms"
}

Conflict, RFI, schedule payload

{
    "analysis_id": "anl_48fa",
    "plan_id": "PRJ-2094",
    "status": "completed",
    "conflicts": [
        {
            "id": "conf_12",
            "summary": "Supply duct clashes with beam at Grid F4",
            "sheet": "M3.12",
            "citation": "See detail 4/M3.12 vs 7/S4.02",
            "severity": "high"
        }
    ],
    "rfi_drafts": [...],
    "schedule": {
        "critical_path": [...]
    },
    "metadata": {
        "sheets_scanned": 128,
        "runtime_seconds": 94
    }
}

Python

import os
import requests

token = os.environ["FOREMANAI_API_KEY"]
payload = {
        "plan_id": "PRJ-2094",
        "modes": ["conflicts", "rfis", "schedule"]
}
resp = requests.post(
    "https://api.foremanai.co/api/v1/plan-analyses",
        headers={"Authorization": f"Bearer {token}"},
        json=payload,
        timeout=90,
)
resp.raise_for_status()
data = resp.json()
print(data["conflicts"][0]["summary"])

JavaScript

const token = process.env.FOREMANAI_API_KEY;
const payload = {
    plan_id: "PRJ-2094",
    modes: ["conflicts", "rfis", "schedule"],
};

const response = await fetch("https://api.foremanai.co/api/v1/plan-analyses", {
    method: "POST",
    headers: {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
});

if (!response.ok) throw new Error("API error");
const data = await response.json();
console.log(data.conflicts[0].citation);

cURL

curl https://api.foremanai.co/api/v1/plan-analyses \
    -H "Authorization: Bearer $FOREMANAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
                "plan_id": "PRJ-2094",
                "modes": ["conflicts", "rfis"],
                "notes": "Level 3 mechanical rooms"
    }'

Core resources.

POST

/api/v1/plan-analyses

Kick off conflict, RFI, schedule, or metadata passes against a registered plan set.

  • plan_id (string)
  • modes (array of enums)
  • notes (optional string)

GET

/api/v1/plan-analyses/<id>

Retrieve the live status plus structured payload for any analysis job.

  • Status: queued → running → completed
  • Embedded conflict / RFI / schedule arrays
  • Sheet-level metadata

GET

/api/v1/conflicts

Filterable conflict log feed for dashboards and reporting (by plan, severity, trade).

  • Query params: plan_id, severity, discipline
  • Returns paginated results with sheet + citation

POST

/api/v1/webhooks

Register webhook targets for job completion, conflict thresholds, or quota events.

  • Supports HTTPS endpoints with shared-secret signing
  • Retries with exponential backoff

What you can expect back.

  • conflicts · Array of objects with summary, sheet, citation, severity, and optional recommendation.
  • rfi_drafts · Includes description, impact, responsible party, and suggested ask text.
  • schedule.critical_path · Ordered tasks with predecessors, durations, and inspection cues.
  • metadata · Sheet counts, runtime, detected disciplines, and submission timestamps.

Every array is capped at 500 items per request; use pagination for bulk exports.

Stay notified without polling.

analysis.completed

Triggered when any plan analysis job finishes processing.

  • Payload includes analysis_id, plan_id, status, and run stats
  • Ideal for telling your PM tool to fetch the final payload

conflict.threshold

Fires when conflict counts exceed the severity mix you configure.

  • Includes top conflicts plus sheet references for alerting
  • Use to notify safety or QA channels in Slack/Teams

quota.window

Gives a heads-up when monthly scans near a percentage threshold.

  • Payload includes remaining scans and reset date
  • Lets you auto-throttle non-critical jobs

All webhook deliveries are signed with an HMAC secret; verify the X-Foreman-Signature header before trusting the payload.

Predictable responses when something goes wrong.

Status When it happens Suggested fix
400 Bad Request Missing plan_id or unsupported mode value. Validate payload fields and re-submit.
401 Unauthorized Token absent, expired, or scoped to another workspace. Rotate the key or confirm you’re hitting the right environment.
409 Conflict An analysis is already running for that plan ID. Use the returned analysis_id to poll status instead of retrying.
429 Too Many Requests Short-term rate limit or monthly quota exceeded. Respect the Retry-After header or request a quota bump.
500 Server Error Unexpected failure on our side. Retry with exponential backoff; include X-Request-ID if contacting support.

Every response carries X-Request-ID — log it so the ForemanAI team can trace issues fast.

Need a deeper integration?

Our team can help you scope custom endpoints, enterprise workflows, and sandbox environments.