Endpoints

HTTP entry points that invoke your AI pipelines with schema validation, API key authentication, and streaming support.

Endpoints are the entry points to your AI workflows. Each endpoint maps an HTTP path to a specific augmentation pipeline. When a request hits the endpoint, the associated pipeline executes with the request payload as input.

Creating an Endpoint

Endpoints are created directly from the pipeline editor top bar. This links the endpoint to the augmentation you're currently editing.

Open the Pipeline Editor

Navigate to your app's Augmentations tab, then open the pipeline you want to expose.

Click Create Endpoint

In the pipeline editor top bar, click the Create Endpoint button.

Configure the Endpoint

Fill in the following fields:

Field	Description
Name	A descriptive name for the endpoint (e.g., "Chat Endpoint")
Path	The URL path that triggers this endpoint (e.g., `/chat`, `/analyze`)
Description	Optional description of what this endpoint does
HTTP Method	The HTTP method to accept (e.g., `POST`, `GET`)
Endpoint Type	The type of endpoint behavior

Define the Input Schema

Optionally configure an input schema using the built-in schema editor. The schema validates incoming request payloads before the pipeline executes. Invalid requests receive a 400 error with details about which fields failed validation.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The user's question"
    },
    "thread_id": {
      "type": "string",
      "description": "Optional conversation thread ID"
    }
  },
  "required": ["query"]
}

Generate an API Key

After creating the endpoint, generate an API key for authentication. This key is used in the Authorization header when calling the endpoint.

API Key Security

API keys are shown only once at creation time. Store them securely. You can generate additional keys or revoke existing ones from the app's Tokens tab.

Request Flow

When a request hits an endpoint, MechaMental processes it through four phases:

Authenticate — validate the API key and check permissions
Validate — check the request payload against the input schema (if defined)
Execute — run the associated augmentation pipeline with the request data as endpoint.payload
Respond — return the pipeline result to the caller (synchronous or streaming)

Calling an Endpoint

Use the generated API key to authenticate requests:

curl -X POST https://api.mechamental.com/v1/trigger/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I reset my password?"}'

The request body is available inside pipeline steps via the endpoint.payload context variable:

{{ endpoint.payload.query }}
{{ endpoint.payload.thread_id }}

Streaming vs Synchronous

Endpoints support two response modes:

Mode	Behavior	Best For
Synchronous	Response returned after the entire pipeline completes	Short-running pipelines, batch processing
Streaming (SSE)	Intermediate results streamed via Server-Sent Events as steps complete	Chat experiences, real-time progress

When streaming is enabled, steps configured with event_action: "primary" emit main response content as SSE events. Steps with event_action: "secondary" emit cognitive chain / reasoning events visible in the Cortex chat UI.

Multiple Endpoints per App

An app can have multiple endpoints, each pointing to a different augmentation pipeline. This lets you expose different capabilities through different paths:

/chat — conversational interaction via a chat pipeline
/analyze — batch analysis via an analysis pipeline
/summarize — document summarization via a summarization pipeline

Each endpoint has its own path, input schema, and API keys, but they all operate within the same app and share access to the app's namespaces, tools, and models.

On this page