API Reference Overview

ConstellationAPI provides a RESTful API for interacting with Jira, GitHub, Confluence, and Notion. Every operation automatically enriches the Sagittarius knowledge graph with entities and relationships. All endpoints return JSON responses and use standard HTTP status codes.

Base URL

http://localhost:3007

For production, replace with your deployed API URL.

Authentication

All protected endpoints require two headers:

X-API-KEY: Your internal API key (for authentication)
X-JWT-Token: JWT token containing tenant and connection credentials

See Authentication Guide for details.

Available Integrations

Integration	Tools	Description
GitHub	27	Repositories, issues, PRs, branches, files, DORA metrics
Jira	24	Projects, tickets, sprints, transitions, throughput metrics
Confluence	14	Spaces, pages, comments, attachments, labels, search
Notion	8	Databases, pages, blocks, properties
Google	25+	Calendar events, Gmail threads/messages, Chat spaces/messages

Total: 98+ API Endpoints available for AI-powered automation.

Knowledge Graph

Every API operation automatically populates the Sagittarius knowledge graph:

Nodes: Users, repositories, PRs, issues, projects, pages, deployments
Edges: AUTHORED_BY, BELONGS_TO, ASSIGNED_TO, DEPLOYED_TO, LINKED_TO
Activity: Full audit trail of all operations

Query the graph via the Graph API or explore visually at /graph/visualizer.

MCP (Model Context Protocol)

ConstellationAPI implements the Model Context Protocol for AI-friendly tool discovery and execution:

Discover Tools: GET /mcp/{system}/tools - Returns all available tools with input schemas
Execute Tools: POST /mcp/{system}/execute - Execute any tool with parameters
List Systems: GET /mcp/systems - Get available systems

See MCP API Reference for complete documentation.

Response Format

Success Response

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "tenant_id": "tenant-123",
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description"
  }
}

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Too Many Requests
500	Internal Server Error

Endpoints by Category

Core

Health Check - Monitor API status
Integrations Metadata - Get available integrations and filterable fields
MCP API - Model Context Protocol for tool discovery and execution
Graph API - Knowledge graph queries, traversal, and visualization
Admin - Connection management and tenant operations

Integrations

GitHub - Repository, issues, PRs, and metrics (27 tools)
Jira - Projects, tickets, sprints, and metrics (24 tools)
Confluence - Spaces, pages, and documentation (14 tools)
Notion - Databases, pages, and blocks (8 tools)

Tool Categories

Read/List Operations

Tools for fetching and listing resources. Most support parallel execution across all accessible resources when the identifier (repo_id, project_key, space_key) is omitted.

Create Operations

Tools for creating new resources (issues, tickets, pages, PRs, branches, etc.).

Update Operations

Tools for modifying existing resources.

Delete Operations

Tools for removing resources.

Metrics Operations

Tools for fetching analytics and metrics:

DORA Metrics: Deployment frequency, lead time, change failure rate, MTTR
Developer Metrics: Commits, PRs, reviews, productivity
Sprint Metrics: Velocity, completion rate, burndown
Throughput Metrics: Cycle time, lead time, WIP
Executive Summary: Health scores, risk indicators, team activity

User Work Operations

Tools for fetching a user's open work across all accessible resources:

get_my_github_work - PRs, reviews, assigned issues
get_my_jira_work - Assigned tickets, blocked items
get_my_confluence_work - Created, modified, draft pages

Filterable Fields for ABAC

Use the /integrations endpoint to get a complete list of available integrations and their filterable fields for Attribute-Based Access Control (ABAC):

curl http://localhost:3007/integrations \
  -H "X-API-KEY: your-internal-key"

This endpoint returns metadata about:

Available integrations (Jira, GitHub, Confluence)
All endpoints for each integration
Filterable fields/parameters for each endpoint
Field types, descriptions, and examples

Caching

Response Caching

All GET requests are cached in Redis for 24 hours (configurable via CACHE_TTL). Cache keys are based on the request path and query parameters.

Connection Caching

Connections to external services (Jira, GitHub, Confluence) are automatically cached per tenant:

Connection Pooling: Connections are reused across requests
Tenant Isolation: Each tenant has separate cached connections
Automatic Management: Connections are created, cached, and expired automatically
TTL: 24 hours (same as response cache)

See Connection Management for details.

Semantic Ontology

The API uses a semantic ontology system to provide concept-based tool definitions for the MCP API. This allows tools to be organized by semantic concepts (Repository, Issue, Ticket, Page, etc.) with consistent property descriptions and types.

Key features:

Concept-Based Organization: Tools are mapped to semantic concepts
Automatic Parameter Descriptions: Parameter descriptions come from concept properties
Type Safety: Parameter types are defined in the ontology
Relationship Modeling: Concepts can define relationships to other concepts

See the Ontology Guide for details on how the semantic ontology works.

Quick Reference

GitHub Tools (27)

Category	Tools
Repositories	`get_repositories`, `get_repository`, `list_repos_by_user`, `get_repository_users`, `get_contributors`
Users	`get_user_by_email`
Issues	`get_issues`, `get_issue`, `create_issue`, `update_issue`, `get_issue_comments`, `add_issue_comment`, `add_issue_labels`, `remove_issue_labels`
Pull Requests	`get_pull_requests`, `get_stale_prs`, `create_pull_request`, `merge_pull_request`
Branches & Files	`create_branch`, `create_or_update_file`
Metrics	`get_dora_metrics`, `get_dora_metrics_by_repo`, `get_developer_metrics`, `get_actions_info`, `get_pr_developer_metrics`, `get_pr_merge_time_metrics`, `get_eng_metrics`, `get_eng_metrics_by_repo`
User Work	`get_my_github_work`

Jira Tools (24)

Category	Tools
Projects	`get_projects`, `get_project_info`, `get_available_statuses`, `get_assignable_users`
Users	`get_users`, `get_user_by_email`, `get_tickets_by_user`
Tickets	`get_tickets`, `get_ticket`, `create_ticket`, `update_ticket`, `get_ticket_comments`, `add_ticket_comment`, `get_available_transitions`, `transition_issue`, `assign_issue`, `get_issues_by_status`, `get_issue_aging`, `add_issue_labels`, `remove_issue_labels`
Metrics	`get_developer_metrics`, `get_dora_metrics`, `get_sprint_metrics`, `get_throughput_metrics`, `get_throughput_metrics_by_project`, `get_project_productivity_metrics`, `get_developer_ticket_metrics_all_projects`, `get_executive_summary_all_projects`
User Work	`get_my_jira_work`

Confluence Tools (14)

Category	Tools
Spaces	`get_spaces`, `get_space`
Pages	`get_pages`, `get_page`, `create_page`, `update_page`, `delete_page`
Comments	`get_page_comments`, `add_comment`
Attachments	`get_attachments`
Search	`search`
Labels	`get_labels`, `add_labels`
Users	`get_user_by_email`, `get_my_confluence_work`

Support

For API support, please visit our GitHub repository or check the Swagger documentation.

Base URL​

Authentication​

Available Integrations​

Knowledge Graph​

MCP (Model Context Protocol)​

Response Format​

Success Response​

Error Response​

HTTP Status Codes​

Endpoints by Category​

Core​

Integrations​

Tool Categories​

Read/List Operations​

Create Operations​

Update Operations​

Delete Operations​

Metrics Operations​

User Work Operations​

Filterable Fields for ABAC​

Caching​

Response Caching​

Connection Caching​

Semantic Ontology​

Quick Reference​

GitHub Tools (27)​

Jira Tools (24)​

Confluence Tools (14)​

Support​