API Full Cycle - End-to-End FDS Agent Flow

This guide documents the complete API lifecycle: health checks, OAuth, JWT generation, build start, publish, status polling, and artifact retrieval. It is intended for API clients and CI integrations.

Base Settings

Base URL: BASE_URL (or http://localhost:4000 locally)
Format: JSON (unless stated otherwise)
Content-Type: application/json

0. Service Health

Health check

GET /status

Version and build info

GET /version

1. Prepare the Recipe

Minimal request example:

{
  "projectName": "my-project",
  "target": "www",
  "recipe": {
    "unit": "layout1",
    "description": "My project",
    "inventory": {},
    "environment": {}
  }
}

Rules:

projectName must be slug format (^[a-z0-9-]+$).
target must be www, ios, or android.
recipe is required and must be an object.
license is always set by the agent to FREE.
branch is set by the agent from build-info.json (or GITHUB_APP_BRANCH, or local).
gqlSchemaMinVersion can be provided; otherwise defaults to 1.
platforms (optional) is an array of targets; the agent always ensures target is included.

2. GitHub OAuth (optional, for GitHub publish)

2.1 Start OAuth

GET /auth/github/start

The response includes a redirectUrl to GitHub.

2.2 OAuth Callback

GitHub redirects the user to:

GET /auth/github/callback?code=...&state=...

After processing, the agent redirects to:

/auth/success.html?session=<SESSION_ID>

2.3 Load Session Data

GET /auth/session/<SESSION_ID>

2.4 Create Repository (optional)

POST /auth/create-repo
Content-Type: application/json

{
  "sessionId": "SESSION_ID",
  "owner": "org-or-user",
  "name": "new-repo",
  "private": false
}

2.5 Generate JWT

POST /auth/generate-jwt
Content-Type: application/json

{
  "sessionId": "SESSION_ID",
  "repo": "owner/repo",
  "branch": "main",
  "path": "dist"
}

The response includes jwt. Pass it to /process as githubJwt.

3. Start a Build

Endpoint:

POST /process
Content-Type: application/json

Example (no GitHub):

{
  "projectName": "my-project",
  "target": "www",
  "gqlSchemaMinVersion": 1,
  "recipe": {
    "unit": "layout1",
    "inventory": {},
    "environment": {}
  }
}

Example (GitHub + Auto-CI):

{
  "projectName": "my-project",
  "target": "android",
  "gqlSchemaMinVersion": 1,
  "githubJwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "autoCi": {
    "enabled": true,
    "workflows": {
      "androidApk": true
    }
  },
  "recipe": {
    "unit": "layout1",
    "inventory": {},
    "environment": {}
  }
}

Response example:

{
  "dataHash": "abc123...",
  "downloadUrl": "/dist/abc123/my-project-1.tar",
  "status": "in_progress",
  "publish": {
    "archive": { "status": "pending" },
    "github": { "status": "pending" }
  }
}

dataHash is a deterministic hash of the normalized request and is used for status polling.

4. Poll Build Status

GET /build-status/<DATA_HASH>

Common status values:

queued
in_progress
build_done
publish_done
error
canceled

Responses may include logs, errors, queue position, and publish details.

5. Cancel a Build (optional)

POST /build-status/<DATA_HASH>/cancel

Cancels queued or running builds.

6. Download the Artifact

The download URL is returned as downloadUrl or publish.archive.url.

Example:

GET /dist/<DATA_HASH>/my-project-1.tar

For ios/android, the URL includes the target:

GET /dist/<DATA_HASH>/<target>/my-project-1.tar

7. GitHub Publish Result (if `githubJwt` provided)

Once publish completes, publish.github contains:

{
  "status": "done",
  "repo": "owner/repo",
  "branch": "main",
  "path": "dist",
  "commit": "abc123..."
}

8. Auto-CI (optional)

Workflow catalog

GET /ci/workflows?target=android&publish=github

List all Auto-CI workflows

Call GET /ci/workflows to get supportedTargets.
For each target, call GET /ci/workflows?target=<target>&publish=github.

Example:

GET /ci/workflows
GET /ci/workflows?target=android&publish=github
GET /ci/workflows?target=ios&publish=github
GET /ci/workflows?target=www&publish=github

Workflow documentation

GET /ci/docs/androidApk
GET /ci/docs/androidApk?format=markdown

Full Flow Summary

GET /status
(Optional) OAuth:
- GET /auth/github/start
- GET /auth/github/callback
- GET /auth/session/:id
- POST /auth/create-repo (if needed)
- POST /auth/generate-jwt
POST /process
GET /build-status/:dataHash (poll until done)
GET /dist/... (download)
Check publish.github if GitHub is enabled

Rendered Documentation

HTML:

GET /docs/API_FULL_CYCLE

Markdown:

GET /docs/API_FULL_CYCLE?format=markdown