Skip to content

Factory API Overview

This document provides a high-level overview of the AI Factory API surface for managing projects, runs, and artifacts. It is written for architects, engineers, and platform owners who need to integrate with the Factory programmatically.

The Factory API enables programmatic access to Factory capabilities, allowing you to trigger runs, check status, and retrieve generated artifacts. This is a conceptual overview—concrete OpenAPI/Swagger documentation lives in the Factory product repository.

Note

This is a conceptual overview of the Factory API. Concrete OpenAPI/Swagger documentation with exact endpoints, request/response schemas, and authentication details lives in the Factory product repository.

API Surface at a Glance

The Factory API provides endpoints for:

  • Projects - Managing Factory projects and blueprints
  • Runs - Triggering and monitoring Factory execution runs
  • Artifacts - Retrieving generated code, pipelines, and documentation
  • Status - Checking run status and execution logs
  • Configuration - Managing Factory configuration and templates

Authentication and Authorization

Internal Usage

  • Service-to-Service - OAuth2 client credentials flow
  • Managed Identity - Azure Managed Identity for Azure-hosted services
  • API Keys - Service API keys for programmatic access

Customer-Facing Usage

  • OAuth2/OIDC - Standard OAuth2 flows for customer access
  • Integration with Identity Platform - Uses ConnectSoft Identity Platform for authentication
  • Tenant Isolation - All operations are scoped to tenants

See: Identity Platform API Overview for authentication details.

Main Resource Groups

Resource Description Typical Clients
Projects Factory projects and blueprints Factory console, CI/CD systems
Runs Factory execution runs Factory console, automation scripts
Artifacts Generated code, pipelines, docs CI/CD systems, development tools
Status Run status and logs Monitoring systems, dashboards
Templates Available templates and libraries Factory console, template management

Common Usage Patterns

Pattern 1: Trigger a Factory Run for New Microservice

Steps: 1. Create or select a Factory project 2. Define bounded context and requirements 3. Trigger a Factory run 4. Monitor run status 5. Retrieve generated artifacts

Example Flow: 

POST /api/v1/projects/{projectId}/runs
{
  "boundedContext": "UserManagement",
  "requirements": "...",
  "template": "microservice"
}

GET /api/v1/runs/{runId}/status
GET /api/v1/runs/{runId}/artifacts

Pattern 2: Check Status and Download Report

Steps: 1. Get run status 2. Check execution logs 3. Download generated artifacts 4. Review quality reports

Example Flow: 

GET /api/v1/runs/{runId}/status
GET /api/v1/runs/{runId}/logs
GET /api/v1/runs/{runId}/artifacts/{artifactId}/download
GET /api/v1/runs/{runId}/quality-report

Pattern 3: Manage Projects and Blueprints

Steps: 1. Create a new project 2. Define project blueprint 3. Update blueprint 4. List projects

Example Flow: 

POST /api/v1/projects
GET /api/v1/projects/{projectId}
PUT /api/v1/projects/{projectId}/blueprint
GET /api/v1/projects

Error Handling and Status Codes

Standard HTTP Status Codes

  • 200 OK - Successful request
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Authentication required
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 409 Conflict - Resource conflict
  • 500 Internal Server Error - Server error
  • 503 Service Unavailable - Service temporarily unavailable

Error Response Format

{
  "error": {
    "code": "RUN_NOT_FOUND",
    "message": "Run with ID 'run-123' not found",
    "details": {
      "runId": "run-123",
      "timestamp": "2026-01-01T10:30:00Z"
    }
  }
}

Versioning and Compatibility

API Versioning

  • URL Versioning - /api/v1/, /api/v2/, etc.
  • Backward Compatibility - Maintain backward compatibility within major versions
  • Deprecation - Deprecate endpoints with advance notice

Compatibility

  • Version Headers - Use API-Version header for version negotiation
  • Feature Flags - Use feature flags for gradual rollout
  • Breaking Changes - New major versions for breaking changes

Tip

Best Practices: 1. Always specify API version in requests 2. Handle version negotiation gracefully 3. Monitor deprecation notices 4. Test against latest API version