Surge AI · OpenAPI Overlay 1.0.0

API Evangelist agent overlay for Surge AI Tasks API

7 actions 7 updates update extends openapi/surge-ai-tasks-api-openapi.yml
Generated by API Evangelist Written by API Evangelist tooling for Surge AI's API. It is a proposal applied on top of the contract, not a document Surge AI publishes.
View Overlay File View on GitHub Overlay Specification

What the actions change

x-agent-safetyx-mcp-toolx-idempotencyexternalDocs

Targets 7

$
$.paths['/projects/{project_id}/tasks'].get
$.paths['/projects/{project_id}/tasks'].post
$.paths['/projects/{project_id}/tasks/create_tasks'].post
$.paths['/tasks/{task_id}'].get
$.paths['/tasks/{task_id}/create-response'].post
$.paths['/tasks/{task_id}/gold-standards'].post

OpenAPI Overlay

Raw ↑ 
overlay: 1.0.0
info:
  title: API Evangelist agent overlay for Surge AI Tasks API
  version: 1.0.0
extends: openapi/surge-ai-tasks-api-openapi.yml
x-generated: '2026-10-27'
x-method: generated
x-source: openapi/surge-ai-tasks-api-openapi.yml
x-rationale: The captured spec has no externalDocs and no per-operation agent hints. This overlay adds the documented
  docs URL, an x-agent-safety class per operation (read-only/mutating/destructive, derived from the HTTP method;
  cancelProject flagged destructive), the candidate MCP tool name from mcp/surge-ai-mcp.yml, and an honest note
  that idempotency for POSTs is undocumented. It does not mutate the original spec.
actions:
- target: $
  description: Link the provider documentation as externalDocs (the captured spec has none).
  update:
    externalDocs:
      description: Surge AI API documentation
      url: https://app.surgehq.ai/docs/api
- target: $.paths['/projects/{project_id}/tasks'].get
  description: Agent hints for listTasks, derived from its HTTP method and summary.
  update:
    x-agent-safety: read-only
    x-mcp-tool: list_tasks
- target: $.paths['/projects/{project_id}/tasks'].post
  description: Agent hints for createTask, derived from its HTTP method and summary.
  update:
    x-agent-safety: mutating
    x-mcp-tool: create_task
    x-idempotency: not documented; treat retries of this POST as able to create duplicates
- target: $.paths['/projects/{project_id}/tasks/create_tasks'].post
  description: Agent hints for createTasksBulk, derived from its HTTP method and summary.
  update:
    x-agent-safety: mutating
    x-mcp-tool: create_tasks_bulk
    x-idempotency: not documented; treat retries of this POST as able to create duplicates
- target: $.paths['/tasks/{task_id}'].get
  description: Agent hints for getTask, derived from its HTTP method and summary.
  update:
    x-agent-safety: read-only
    x-mcp-tool: get_task
- target: $.paths['/tasks/{task_id}/create-response'].post
  description: Agent hints for createTaskResponse, derived from its HTTP method and summary.
  update:
    x-agent-safety: mutating
    x-mcp-tool: create_task_response
    x-idempotency: not documented; treat retries of this POST as able to create duplicates
- target: $.paths['/tasks/{task_id}/gold-standards'].post
  description: Agent hints for setTaskGoldStandards, derived from its HTTP method and summary.
  update:
    x-agent-safety: mutating
    x-mcp-tool: set_task_gold_standards
    x-idempotency: not documented; treat retries of this POST as able to create duplicates

Work with this as data

Every overlay here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for openapi overlays

4 MCP tools reach this
  • find_overlaysBrowse and filter every overlay in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This overlay 
curl "https://apis.io/api/v1/overlays/surge-ai-tasks-api-overlay"
All openapi overlays 
curl "https://apis.io/api/v1/overlays?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.