Agentic API

The HTTP product surface and shared contract behind Atlas MCP and SDK.

The Agentic API is the HTTP product surface for Atlas. MCP and SDK also use this contract after adapting their local or typed inputs.

​

Responsibilities

The API owns the request envelope, response envelope, permission checks, full object retrieval, file resources, artifact resources, run lifecycle, and action approval.

MCP adapts API results to MCP text, structured content, and resources. SDK provides typed wrappers over the same contracts.

​

Authenticate

Requests that read or modify user-owned resources include user-level auth. Application integrations also identify the developer application.

POST /api/v1/agentic/requests HTTP/1.1
Host: atlas.example.com
Authorization: Bearer <atlas-user-access-token>
X-Atlas-Developer-Key: <developer-key>
Content-Type: application/json

MCP calls do not require the caller to supply a developer key. Atlas identifies those clients from Atlas-managed client configuration. SDK and direct API integrations include application identity and end-user identity.

​

Upload Files

Local surfaces upload files before they create remote Atlas requests. The upload response is the file handle used by API, SDK, and remote MCP calls.

POST /api/v1/agentic/files HTTP/1.1
Host: atlas.example.com
Authorization: Bearer <atlas-user-access-token>
X-Atlas-Developer-Key: <developer-key>
Content-Type: multipart/form-data

{
  "id": "file_123",
  "name": "imu-bringup.txt",
  "mime_type": "text/plain",
  "size_bytes": 28491,
  "uri": "atlas://file/file_123"
}

​

Create a Request

The request envelope contains input, caller-provided context, uploaded file IDs, and options. Headers carry user and developer auth.

POST /api/v1/agentic/requests HTTP/1.1
Host: atlas.example.com
Authorization: Bearer <atlas-user-access-token>
X-Atlas-Developer-Key: <developer-key>
Content-Type: application/json

{
  "input": "Summarize this failed IMU bring-up log and find related issues.",
  "context": {
    "session_id": "session_123",
    "metadata": {
      "source": "bringup-notebook"
    }
  },
  "files": [
    {
      "id": "file_123",
      "source": "uploaded"
    }
  ],
  "options": {
    "output": "default",
    "object_detail": "compact"
  }
}

type AtlasRequest = {
  input: string;
  context?: {
    session_id?: string;
    metadata?: Record<string, string>;
    inline_text?: Array<{
      name?: string;
      text: string;
      mime_type?: string;
    }>;
  };
  files?: Array<{
    id: string;
    source: "uploaded";
  }>;
  options?: {
    output?: "default" | "json";
    object_detail?: "compact" | "full";
  };
};

The API evaluates the user token, attaches caller-provided files, and creates a response.

​

Run Lifecycle

Use a run for work that needs durable status, event streaming, cancellation, or later retrieval. A run uses the same user auth, input, context, and uploaded file handles as a request.

​

Create a Run

POST /api/v1/agentic/runs HTTP/1.1
Host: atlas.example.com
Authorization: Bearer <atlas-user-access-token>
X-Atlas-Developer-Key: <developer-key>
Content-Type: application/json

{
  "input": "Investigate this failed test and produce an artifact.",
  "files": [
    {
      "id": "file_123"
    }
  ]
}

​

Stream Run Events

GET /api/v1/agentic/runs/run_123/events HTTP/1.1
Host: atlas.example.com
Authorization: Bearer <atlas-user-access-token>
X-Atlas-Developer-Key: <developer-key>
Accept: text/event-stream

Run event streams emit progress, status changes, returned objects, files, artifacts, proposed actions, and completion state.

​

Retrieve a Run

GET /api/v1/agentic/runs/run_123 HTTP/1.1
Host: atlas.example.com
Authorization: Bearer <atlas-user-access-token>
X-Atlas-Developer-Key: <developer-key>

​

Cancel a Run

POST /api/v1/agentic/runs/run_123/cancel HTTP/1.1
Host: atlas.example.com
Authorization: Bearer <atlas-user-access-token>
X-Atlas-Developer-Key: <developer-key>

​

Read Results

A request returns a response envelope for that request. A completed run exposes the same output collections. Object results include compact Atlas records. File and artifact results include metadata and links for later fetches.

{
  "answer": "The evidence matches one prior IMU SPI timing issue.",
  "objects": [
    {
      "id": "issue_123",
      "type": "issue",
      "title": "Intermittent IMU SPI read failure",
      "status": "open",
      "summary": "Prior rev C reports show the same SPI read pattern."
    }
  ],
  "files": [],
  "artifacts": [
    {
      "id": "artifact_456",
      "artifact_type": "investigation_summary",
      "name": "investigation-summary.pdf",
      "status": "completed",
      "files": [
        {
          "id": "file_789",
          "name": "investigation-summary.pdf",
          "mime_type": "application/pdf",
          "source": "generated"
        }
      ]
    }
  ],
  "actions": [],
  "links": [],
  "metadata": {
    "session_id": "session_123",
    "request_id": "request_456"
  }
}

The response envelope has the same shape across API, SDK, and MCP structured content.

type AtlasResponse = {
  answer: string;
  objects: AtlasObject[];
  files: AtlasFile[];
  artifacts: AtlasArtifact[];
  actions: AtlasProposedAction[];
  links: AtlasLink[];
  events?: AtlasEvent[];
  metadata: AtlasResponseMetadata;
};

type AtlasObject = {
  id: string;
  type: "issue" | "run" | "system" | "asset";
  title?: string;
  name?: string;
  status?: string;
  summary?: string;
  link?: string;
};

type AtlasProposedAction = {
  id: string;
  type: string;
  label: string;
  risk: "write" | "destructive";
  status: "proposed" | "approved" | "rejected" | "completed";
  target?: {
    type: "issue" | "run" | "system" | "asset";
    id: string;
  };
};

​

Retrieve Full Objects

GET /api/v1/agentic/objects/issue/issue_123 HTTP/1.1
Host: atlas.example.com
Authorization: Bearer <atlas-user-access-token>
X-Atlas-Developer-Key: <developer-key>

Full object retrieval returns the public fields for a compact object returned by Atlas.

​

Download Returned Files and Artifacts

GET /api/v1/agentic/files/file_789/download HTTP/1.1
Host: atlas.example.com
Authorization: Bearer <atlas-user-access-token>
X-Atlas-Developer-Key: <developer-key>

GET /api/v1/agentic/artifacts/artifact_456 HTTP/1.1
Host: atlas.example.com
Authorization: Bearer <atlas-user-access-token>
X-Atlas-Developer-Key: <developer-key>

Atlas applies the same permission check when a file or artifact is fetched.

​

Approve Actions

POST /api/v1/agentic/actions/action_789/approve HTTP/1.1
Host: atlas.example.com
Authorization: Bearer <atlas-user-access-token>
X-Atlas-Developer-Key: <developer-key>

Atlas validates the user’s permissions at approval time.