> ## Documentation Index
> Fetch the complete documentation index at: https://atlas-platform.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```http theme={null}
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.

```http theme={null}
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
```

```json theme={null}
{
  "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.

```http theme={null}
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"
  }
}
```

```ts theme={null}
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

```http theme={null}
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

```http theme={null}
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

```http theme={null}
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

```http theme={null}
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.

```json theme={null}
{
  "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.

```ts theme={null}
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

```http theme={null}
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

```http theme={null}
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>
```

```http theme={null}
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

```http theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.