Stellr API Reference

Integrate context-aware execution into your applications. The v1 API empowers developers to bind tools and interact with the Exegesis Centralized Execution (CE) engine seamlessly.

POST

/v1/tools

OAuth Consent: Tool Dependent Depends: SDKs

Allows direct utilization of a tool. The authorization provided must match the owner of the tool being called. This endpoint is fundamental for manually triggering registered actions.

Dependencies & Context

Depends on OrrinAISDK & tool existence. Use the OrrinToolsSDK to create a tool that will be available through this endpoint.

Headers

authorization string Required

Developer: Dev Bearer <developer_api_key>

User: Bearer <account_id> (Must be an account ID from a user subscribed to Orrin)

{
  "toolId": "<tool_id>",
  "action": "<tool_action>",
  "payload": "<payload_for_action>"
}
200 OK - Success; tool was called & returned successfully 
{
  "response": "<action_response>"
}
400 Bad Request - Failure; malformed request body, not owner, invalid auth, or not subscribed (not a developer) 
{
  "status": 400,
  "message": "<error_message>"
}
404 Not Found - Failure; resources not found 
{
  "status": 404,
  "message": "<error_message>"
}
500 Internal Error - Internal failure; something went wrong internally processing the request 
{
  "status": 500,
  "message": "<error_message>"
}

/v1/exegesis Base Headers

All requests directed to the /v1/exegesis endpoint group require the following authorization structure. You must provide either a Developer or User Bearer token to successfully authenticate your requests.

authorization string Required

Developer: Dev Bearer <developer_api_key>

User:

Bearer <account_id> (Must be an account ID from a user subscribed to Orrin)

POST

/v1/exegesis

Auth: Required OAuth Consent: Tool Dependent Depends: SDKs

Requests to Exegesis Centralized Execution (CE). This specific payload initializes a new context-aware chat session and returns a connection ID for subsequent requests.

Dependencies & Context

Depends on OrrinAISDK & tool existence. Use the OrrinToolsSDK to create a tool. Exegesis CE requires tool dependence to function.

See Header 
{
  "type": "start_chat",
  "connectedToolId": "<tool_id>"
}
200 OK Store connection ID safely; needed to refer to chat/obtain info later. 
{
  "status": 200,
  "connection_id": "<connection_id>"
}
400 Bad Request - Failure; malformed request body, user not subscribed, or not developer 
{
  "status": 400,
  "message": "user_not_subscribed"
}
404 Not Found - Failure; tool not found or user/developer not found 
{
  "status": 404,
  "message": "<error_message>"
}
500 Internal Error - Internal failure; something went wrong internally processing the request 
{
  "status": 500,
  "message": "<error_message>"
}
POST

/v1/exegesis

Auth: Required OAuth Consent: Tool Dependent Depends: SDKs

Retrieves existing chat details for a specific connection. Messages meant for contextual AI reference only (and should be ignored in user UI) will contain an ignore: true flag.

Dependencies & Context

Depends on OrrinAISDK & tool existence. Use the OrrinToolsSDK to create a tool. Exegesis CE requires tool dependence to function.

See Header 
{
  "type": "get_chat_details",
  "connection_id": "<chat_connection_id>"
}
200 OK 
{
  "status": 200,
  "connection": {
    "messages": [
      <messages>
    ],
    "actions": [
      <actions_performed>
    ]
  }
}
400 Bad Request - Failure; malformed request body, user not subscribed, or not developer 
{
  "status": 400,
  "message": "user_not_subscribed"
}
404 Not Found - Failure; chat (connection) or user/dev not found 
{
  "status": 404,
  "message": "<error_message>"
}
500 Internal Error - Internal failure; something went wrong internally processing the request 
{
  "status": 500,
  "message": "<error_message>"
}
POST

/v1/exegesis

Auth: Required OAuth Consent: Tool Dependent Depends: SDKs

Sends input to an active connection. The AI evaluates context and decides whether to respond formally with text, recommend an action, or force an action on the user's behalf.

Dependencies & Context

Depends on OrrinAISDK & tool existence. Use the OrrinToolsSDK to create a tool. Exegesis CE requires tool dependence to function.

See Header 
{
  "type": "send_input",
  "connection_id": "<connection_id>",
  "message": "<message>"
}
200 OK Type: Recommended

Success; recommends an action. Store response_id to perform it later.

{
  "status": 200,
  "type": "recommended",
  "response_id": "<response_id>",
  "response": {
    "action_name_recommended": "<action_name>",
    "data": "<payload_for_action>"
  }
}
200 OK Type: Forced

Success; action was autonomously performed on user's behalf.

{
  "status": 200,
  "type": "forced",
  "response_id": "<response_id>",
  "response": {
    "action_name_used": "<action_name>",
    "result": "<result_of_action>",
    "data": "<payload_for_action>"
  }
}
200 OK Type: Text

Success; formal AI text response, no action taken.

{
  "status": 200,
  "type": "text",
  "response_id": "<response_id>",
  "response": "<ai_text_response>"
}
400 Bad Request - Failure; malformed request body, user not subscribed, or not developer 
{
  "status": 400,
  "message": "<error_message>"
}
404 Not Found - Failure; tool backend, connection, or user/developer not found 
{
  "status": 404,
  "message": "<error_message>"
}
500 Internal Error - Internal failure; something went wrong internally processing the request 
{
  "status": 500,
  "message": "<error_message>"
}
POST

/v1/exegesis

Auth: Required OAuth Consent: Tool Dependent Depends: SDKs

Executes a previously recommended action provided by the AI. This allows explicit user confirmation of suggested tool interactions by supplying the connection ID alongside the response ID.

Dependencies & Context

Depends on OrrinAISDK & tool existence. Use the OrrinToolsSDK to create a tool. Exegesis CE requires tool dependence to function.

See Header 
{
  "type": "perform_recommended_action",
  "connection_id": "<connection_id>",
  "response_id": "<response_id>"
}
200 OK - Success; performed recommended action 
{
  "status": 200,
  "type": "forced",
  "response_id": "<response_id>",
  "response": {
    "action_name_used": "<action_name>",
    "result": "<result_of_action>",
    "data": "<payload_for_action>"
  }
}
400 Bad Request - Failure; malformed request body, user not subscribed, not developer, or action is not a recommended action 
{
  "status": 400,
  "message": "<error_message>"
}
404 Not Found - Failure; connection was not found, no such user/developer found, response not found, or tool was not found 
{
  "status": 404,
  "message": "<error_message>"
}
500 Internal Error - Internal failure; something went wrong internally processing the request 
{
  "status": 500,
  "message": "<error_message>"
}

/v1/orrin Base Headers

All requests directed to the /v1/orrin endpoint require OAuth Consent, along with the following authorization structure and the target user's account ID.

authorization string Required

Developer: Dev Bearer <developer_api_key>

User:

Bearer <account_id> (Must be subscribed Orrin user)

for-account string Required

Value: <end_user_account_id>

POST

/v1/orrin

Auth: Required OAuth Consent: Required

Retrieves existing documents from a users Orrin account. You are required to provide tool_id or oauth_id to confirm user account authentication.

See Header
Option 1: Using tool_id 
{
  "type": "obtain_docs",
  "tool_id": "<tool_id>"
}
Option 2: Using oauth_id 
{
  "type": "obtain_docs",
  "oauth_id": "<oauth_id>"
}
200 OK 
{
  "status": 200,
  "documents": [
    <documents_object>
  ]
}
400 Bad Request - Failure; malformed data, user needs authorized, or oauth not found 
{
  "status": 400,
  "message": "<error_message>"
}
404 Not Found - Failure; user not found or resources were not found 
{
  "status": 404,
  "message": "<error_message>"
}
POST

/v1/orrin

Auth: Required OAuth Consent: Required

Creates a new document. Supply the document name and its markdown content. You are required to provide tool_id or oauth_id to confirm user account authentication.

See Header
Option 1: Using tool_id 
{
  "type": "create_doc",
  "tool_id": "<tool_id>",
  "document_name": "<name_of_new_document>",
  "markdown": "<markdown_content_for_new_document>"
}
Option 2: Using oauth_id 
{
  "type": "create_doc",
  "oauth_id": "<oauth_id>",
  "document_name": "<name_of_new_document>",
  "markdown": "<markdown_content_for_new_document>"
}
200 OK 
{
  "status": 200,
  "message": "document_created",
  "document_structure": {
    <document_structure_object>
  }
}
400 Bad Request - Failure; malformed data, user needs authorized, or oauth not found 
{
  "status": 400,
  "message": "<error_message>"
}
404 Not Found - Failure; user not found or resources were not found 
{
  "status": 404,
  "message": "<error_message>"
}
POST

/v1/orrin

Auth: Required OAuth Consent: Required

Deletes an existing document. Specify the document name. You are required to provide tool_id or oauth_id to confirm user account authentication.

See Header
Option 1: Using tool_id 
{
  "type": "delete_doc",
  "tool_id": "<tool_id>",
  "document_name": "<name_of_document_to_delete>"
}
Option 2: Using oauth_id 
{
  "type": "delete_doc",
  "oauth_id": "<oauth_id>",
  "document_name": "<name_of_document_to_delete>"
}
200 OK 
{
  "status": 200,
  "message": "document_deleted"
}
400 Bad Request - Failure; malformed data, user needs authorized, or oauth not found 
{
  "status": 400,
  "message": "<error_message>"
}
404 Not Found - Failure; user not found or resources were not found 
{
  "status": 404,
  "message": "<error_message>"
}