APIs

The DevOps / GitOps Platform exposes a small, stable surface of REST APIs consumed primarily by the Agent Mesh DevOps & Release cluster and the Factory Studio DevOps Center. Resource paths follow the naming conventions: plural, lowercase, hyphenated collection nouns with verb sub-paths for non-CRUD actions.

Target Architecture — Final-State Design

The 10 endpoints below are the primary public contract. Additional internal endpoints exist per service but are not part of the cross-platform surface.

API Surface Overview

#	Method & Path	Service	Purpose
1	POST /repositories	RepositoryService	Provision a repository
2	POST /repositories/{repoId}/branches	BranchService	Create a branch
3	POST /repositories/{repoId}/commits	CommitService	Author a commit
4	POST /pull-requests	PullRequestService	Open a pull request
5	GET /pull-requests/{pullRequestId}	PullRequestService	Retrieve a pull request
6	POST /pipelines/generate	PipelineGeneratorService	Generate a pipeline definition
7	POST /pipelines/{pipelineId}/run	PipelineExecutionService	Trigger a pipeline run
8	POST /releases	ReleaseService	Plan a release
9	POST /releases/{releaseId}/approve	ReleaseService	Approve a release
10	POST /iac/provision	IaCProvisioningService	Provision infrastructure (Pulumi)

Public APIs

These endpoints are exposed through the factory API gateway and consumed by agents and Studio.

1. Provision a repository

POST /repositories
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "moduleId": "module-reservations-api",
  "name": "reservations-api",
  "provider": "AzureDevOps",
  "defaultBranch": "main",
  "visibility": "private"
}

{
  "repositoryId": "repo-7a1c",
  "remoteUrl": "https://dev.azure.com/connectsoft/proj-booking-saas/_git/reservations-api",
  "defaultBranch": "main",
  "status": "Provisioned"
}

2. Create a branch

POST /repositories/repo-7a1c/branches
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "name": "feature/reservation-cancellation",
  "fromBranch": "main"
}

{
  "branchId": "branch-22e9",
  "name": "feature/reservation-cancellation",
  "fromCommit": "9f1c2b7d",
  "status": "Created"
}

3. Author a commit

POST /repositories/repo-7a1c/commits
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "branch": "feature/reservation-cancellation",
  "message": "feat: add reservation cancellation endpoint",
  "artifactId": "art-reservations-api-3c",
  "changes": [
    { "path": "src/Controllers/ReservationsController.cs", "operation": "modify" }
  ]
}

{
  "commitId": "commit-5d4a",
  "sha": "a1b2c3d4",
  "branch": "feature/reservation-cancellation",
  "status": "Committed"
}

4. Open a pull request

POST /pull-requests
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "repositoryId": "repo-7a1c",
  "sourceBranch": "feature/reservation-cancellation",
  "targetBranch": "main",
  "title": "Add reservation cancellation",
  "description": "Implements cancellation for module-reservations-api"
}

{
  "pullRequestId": "pr-9931",
  "number": 42,
  "status": "Open",
  "policyEvaluation": "Pending"
}

5. Retrieve a pull request

GET /pull-requests/pr-9931

{
  "pullRequestId": "pr-9931",
  "number": 42,
  "status": "Open",
  "sourceBranch": "feature/reservation-cancellation",
  "targetBranch": "main",
  "checks": [
    { "name": "build", "status": "Succeeded" },
    { "name": "policy-gate", "status": "Pending" }
  ],
  "reviewers": ["agent:PullRequestCreator"]
}

6. Generate a pipeline

POST /pipelines/generate
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "repositoryId": "repo-7a1c",
  "moduleId": "module-reservations-api",
  "moduleType": "Microservice",
  "targetFeed": "connectsoft-internal"
}

{
  "pipelineId": "pipe-4f12",
  "definitionPath": ".azuredevops/pipelines/reservations-api.yml",
  "status": "Generated"
}

7. Run a pipeline

POST /pipelines/pipe-4f12/run
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "branch": "main",
  "reason": "ci"
}

{
  "pipelineRunId": "run-8c20",
  "buildNumber": "20260611.3",
  "status": "Started"
}

8. Plan a release

POST /releases
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "moduleId": "module-reservations-api",
  "buildResultId": "build-7711",
  "targetEnvironment": "staging",
  "strategy": "RollingUpdate"
}

{
  "releaseId": "rel-3120",
  "version": "1.4.0",
  "status": "Planned",
  "requiredApprovals": 1
}

9. Approve a release

POST /releases/rel-3120/approve
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "approver": "agent:ReleaseManager",
  "decision": "Approved",
  "comment": "Policy gate passed; staging soak complete"
}

{
  "releaseId": "rel-3120",
  "approvalId": "appr-66a1",
  "status": "Approved",
  "nextStep": "Promote"
}

10. Provision infrastructure

POST /iac/provision
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "environment": "staging",
  "engine": "Pulumi",
  "stack": "booking-saas-staging",
  "program": "ConnectSoft.Factory.DevOps.Infra.BookingSaas"
}

{
  "infrastructurePlanId": "infra-5a90",
  "previewSummary": { "create": 7, "update": 2, "delete": 0 },
  "status": "Applying"
}

Internal APIs

Service-to-service endpoints not exposed externally include build-result ingestion (POST /build-results), manifest rendering (POST /deployment-manifests), promotion orchestration (POST /promotions), package publication (POST /packages), container builds (POST /container-images), and GitOps reconciliation triggers (POST /gitops/reconcile). They share the same envelope, auth, and tenancy rules as the public surface.

gRPC APIs

High-throughput, low-latency paths are also offered over gRPC (via ConnectSoft.Extensions.ServiceModel.Grpc):

• PipelineExecution.StreamRunLogs — server-streaming pipeline log tail.
• BuildResult.GetBuildResult — unary build-result fetch for agents.
• GitOpsSync.WatchSyncState — server-streaming reconciliation status.

Authorization

• All endpoints require an OAuth2 / OpenID Connect bearer token issued by the factory authorization server (ConnectSoft.AuthorizationServerTemplate).
• Scopes are coarse-grained per context (devops.repositories.write, devops.releases.approve, devops.iac.provision) and refined by tenant- and project-scoped policy evaluated by the Governance, Security & Compliance Platform.
• Release approval (POST /releases/{releaseId}/approve) additionally enforces segregation-of-duties: the approving identity must differ from the planning identity.

Versioning

• APIs are versioned via the Accept: application/json; version=1 header; the default is the latest stable version.
• Breaking changes introduce a new version and run side by side; deprecation is announced through the Integration Platform catalog.
• Request/response payloads tolerate unknown fields for forward compatibility, mirroring the event envelope rules.

Related

• Microservices
• Workflows
• Security