Documentation navigation

Djass Projects API (v1)

Base URL: https://djass.dev/api/v1 Coverage: create, list, get, status, and download endpoints for project generation.


1) What this API does

This API lets an agent: 1. inspect the current generator option catalog, 2. create a new Djass project generation job, 3. list the caller's projects, 4. fetch one project by id, 5. poll status until generation is complete, 6. download the generated project ZIP artifact.

All data access is owner-scoped: keys can only see projects for their own profile.


2) Authentication and key scoping

Project mutation and project history endpoints require an API key. The generator option catalog is public.

Accepted auth formats (in lookup order)

  1. X-API-Key: <key>
  2. Authorization: Bearer <key> (also accepts Api-Key, apikey, token schemes)
  3. Query fallback: ?api_key=<key> (legacy compatibility)

Key types

  • Legacy profile key: full access to projects:create + projects:read
  • Scoped API key (ProjectAPIKey): only granted scopes

Required scopes

  • POST /projects requires projects:create
  • GET /projects, GET /projects/{id}, GET /projects/{id}/status, and GET /projects/{id}/download require projects:read
  • GET /project-options does not require authentication

If scope is missing: 403 with error.code = "insufficient_scope".


3) Error contract (all non-2xx)

{
  "error": {
    "code": "machine_readable_code",
    "category": "validation|auth|quota|retryable|internal",
    "message": "Human readable summary",
    "retryable": false,
    "details": {}
  }
}

Common codes used by this API

  • auth_required
  • insufficient_scope
  • subscription_required
  • invalid_project_slug
  • quota_exceeded
  • project_not_found
  • artifact_not_ready
  • retryable_error
  • internal_error

Retry guidance may appear in error.details.retry_guidance.


4) Endpoint reference

4.1 Project options

Method/Path: GET /project-options Purpose: return the current generator option catalog grouped for UI/API clients.

Success response (200)

{
  "defaults": {
    "project_name": "My Awesome Project",
    "project_slug": "{{ cookiecutter.project_name.lower()|replace(' ', '_')|replace('-', '_')|replace('.', '_')|trim() }}",
    "caprover_app_name": "{{ cookiecutter.project_slug|replace('_', '-') }}",
    "repo_url": "https://github.com/cookiecutter/cookiecutter",
    "use_posthog": "y",
    "use_chatwoot": "n",
    "use_apprise": "n",
    "use_qdrant": "n",
    "use_mcp": "n"
  },
  "groups": [
    {
      "key": "monitoring",
      "label": "Monitoring",
      "options": [
        {
          "key": "use_posthog",
          "label": "Use PostHog",
          "description": "Adds product analytics. Backend logs use standard Python logging so PostHog Logs can read the same structured fields when its handler is attached.",
          "default": "y",
          "category": "monitoring"
        }
      ]
    }
  ]
}

Notes: - defaults mirrors the typed generator option catalog used by Djass. - groups contains feature flags only, with labels and descriptions for UI/API clients. - Identity and metadata fields stay in the create payload. - create requests use the same flat option keys shown in groups[].options[].

4.2 Create project

Method/Path: POST /projects Purpose: queue project generation from template settings.

Request body

{
  "project_name": "Acme CRM",
  "project_slug": "acme_crm",
  "caprover_app_name": "acme-crm",
  "project_description": "Internal CRM for support and sales",
  "repo_url": "https://github.com/acme/acme-crm",
  "author_name": "Acme Bot",
  "author_email": "[email protected]",
  "author_url": "https://acme.test",
  "project_main_color": "green",
  "use_posthog": "y",
  "use_chatwoot": "n",
  "use_s3": "y",
  "use_qdrant": "n",
  "use_stripe": "y",
  "use_sentry": "y",
  "generate_blog": "y",
  "generate_docs": "y",
  "use_mjml": "y",
  "use_ai": "y",
  "use_healthchecks": "y",
  "use_apprise": "n",
  "use_mcp": "n",
  "use_ci": "y"
}

Notes: - all feature flags are "y"|"n" - use GET /project-options to discover the current supported generator flags - project_slug is normalized (slugify, then - -> _) - if author_email is empty, backend fills it from profile email

Success response (201)

{
  "project": {
    "id": 123,
    "name": "Acme CRM",
    "slug": "acme_crm",
    "status": "queued",
    "error_message": "",
    "created_at": "2026-03-11T12:00:00Z",
    "updated_at": "2026-03-11T12:00:00Z",
    "started_at": null,
    "finished_at": null,
    "artifact_ready": false,
    "input_payload": {
      "project_name": "Acme CRM",
      "project_slug": "acme_crm",
      "caprover_app_name": "acme-crm",
      "project_description": "Internal CRM for support and sales",
      "repo_url": "https://github.com/acme/acme-crm",
      "author_name": "Acme Bot",
      "author_email": "[email protected]",
      "author_url": "https://acme.test",
      "project_main_color": "green",
      "use_posthog": "y",
      "use_chatwoot": "n",
      "use_s3": "y",
      "use_qdrant": "n",
      "use_stripe": "y",
      "use_sentry": "y",
      "generate_blog": "y",
      "generate_docs": "y",
      "use_mjml": "y",
      "use_ai": "y",
      "use_healthchecks": "y",
      "use_apprise": "n",
      "use_mcp": "n",
      "use_ci": "y"
    }
  }
}

Error statuses

  • 400 invalid payload / invalid slug
  • 401 missing or invalid key
  • 402 paid access required when payment enforcement is enabled
  • 403 insufficient scope
  • 429 project quota exceeded
  • 503 temporary queueing failure (retryable)
  • 500 internal error

4.3 List projects

Method/Path: GET /projects Purpose: list caller-owned projects with pagination and optional status filter.

Query params

  • limit (default 20, min 1, max 100)
  • offset (default 0, min 0)
  • status (queued|generating|ready|failed)

Success response (200)

{
  "projects": [
    {
      "id": 123,
      "name": "Acme CRM",
      "slug": "acme_crm",
      "status": "ready",
      "error_message": "",
      "created_at": "2026-03-11T12:00:00Z",
      "updated_at": "2026-03-11T12:02:40Z",
      "started_at": "2026-03-11T12:00:05Z",
      "finished_at": "2026-03-11T12:02:39Z",
      "artifact_ready": true,
      "input_payload": {
        "project_name": "Acme CRM",
        "project_slug": "acme_crm"
      }
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0,
  "has_next": false,
  "filters": {
    "status": "ready"
  }
}

Error statuses

  • 401 missing or invalid key
  • 403 insufficient scope
  • 422 invalid query params (limit/offset/status)
  • 500 internal error

4.4 Get project

Method/Path: GET /projects/{project_id} Purpose: fetch one full project object.

Success response (200)

Returns full Project object (same shape as project in create response).

Error statuses

  • 401 missing/invalid key
  • 403 insufficient scope
  • 404 project not found
  • 500 internal error

4.5 Get project status

Method/Path: GET /projects/{project_id}/status Purpose: lightweight polling endpoint.

Success response (200)

{
  "id": 123,
  "status": "generating",
  "error_message": "",
  "artifact_ready": false,
  "started_at": "2026-03-11T12:00:05Z",
  "finished_at": null,
  "updated_at": "2026-03-11T12:00:20Z"
}

Error statuses

  • 401 missing/invalid key
  • 403 insufficient scope
  • 404 project not found
  • 500 internal error

4.6 Download project artifact

Method/Path: GET /projects/{project_id}/download Purpose: download the generated repository ZIP after project generation is ready.

Success response (200)

Returns a binary ZIP stream with:

  • Content-Type: application/zip
  • Content-Disposition: attachment; filename="<project_slug>-YYYYMMDD.zip"

Error statuses

  • 401 missing/invalid key
  • 403 insufficient scope
  • 404 project not found
  • 409 artifact is not ready yet
  • 500 internal error

When the artifact is not ready, poll GET /projects/{project_id}/status until artifact_ready is true.


5) Agent quickstart (copy-paste)

# 0) Set runtime values
export DJASS_BASE_URL="https://djass.dev/api/v1"
export DJASS_API_KEY="replace-with-key"

# 1) Create project
curl -sS -X POST "$DJASS_BASE_URL/projects" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DJASS_API_KEY" \
  --data '{
    "project_name": "Acme CRM",
    "project_slug": "acme_crm",
    "caprover_app_name": "acme-crm",
    "project_description": "Internal CRM for support and sales",
    "repo_url": "https://github.com/acme/acme-crm",
    "author_name": "Acme Bot",
    "author_email": "[email protected]",
    "author_url": "https://acme.test",
    "project_main_color": "green",
    "use_posthog": "y",
    "use_chatwoot": "n",
    "use_s3": "y",
    "use_qdrant": "n",
    "use_stripe": "y",
    "use_sentry": "y",
    "generate_blog": "y",
    "generate_docs": "y",
    "use_mjml": "y",
    "use_ai": "y",
    "use_healthchecks": "y",
    "use_apprise": "n",
    "use_mcp": "n",
    "use_ci": "y"
  }'

# 2) Copy project.id from the successful create response; 123 is an example
PROJECT_ID="123"

# 3) Read status for that exact project
curl -sS "$DJASS_BASE_URL/projects/$PROJECT_ID/status" \
  -H "X-API-Key: $DJASS_API_KEY"

# 4) Fetch full project object
curl -sS "$DJASS_BASE_URL/projects/$PROJECT_ID" \
  -H "X-API-Key: $DJASS_API_KEY"

# 5) Download generated repo ZIP when ready
curl -L "$DJASS_BASE_URL/projects/$PROJECT_ID/download" \
  -H "X-API-Key: $DJASS_API_KEY" \
  -o "acme_crm.zip"

These are separate commands, not an automatic polling script. Save the successful create response and use its project.id for every later step. Do not substitute the newest item from a project list: another client may have created it. Run the download command only after status is ready and artifact_ready is true, and choose a new destination filename.

For a client polling policy, start at two seconds and back off to at most 15 seconds between reads. Set an overall deadline. Stop on failed; on ready, check artifact_ready before downloading. These intervals are recommendations, not a completion-time promise or a server-provided retry schedule.

Resume an interrupted generation

A client timeout does not prove that Djass rejected the request. Resume the existing project before creating another one. The current Projects API has no idempotency-key contract: repeating POST /projects can create another project, even with the same slug. An error.retryable flag is not a deduplication guarantee. A queueing failure can also occur after a project row was created.

If you have the project ID

  1. Read GET /projects/{project_id}/status with the same account and a key granting projects:read. Resume reads for queued or generating; do not submit another create request merely because your agent stopped waiting.
  2. On failed, stop and inspect error_message. Resolve the cause before choosing a new generation. A download retry does not restart generation.
  3. On ready with artifact_ready: true, download the ZIP for that ID. If the transfer fails, retry the download with bounded backoff, not project creation.
  4. If the project remains queued or generating past your deadline, keep the ID and report the last observed state. A row's existence does not prove a worker received the job. Do not delete it or create replacements automatically.

If the create response was lost

List your own projects without a status filter:

curl -sS "$DJASS_BASE_URL/projects?limit=100&offset=0" \
  -H "X-API-Key: $DJASS_API_KEY"

Compare created_at, name, slug, and input_payload with the request you submitted. If has_next is true, increase offset by the number of projects returned and continue. A slug is not a unique request identifier. If more than one project matches, or no definite match is found, report that uncertainty instead of downloading a guessed project or blindly sending another POST.

For 401 or 403, fix the account/key/scope before retrying. A create-only key cannot perform this recovery. For 402 or 429, resolve paid access or quota; waiting and repeating the same request does not fix those conditions. Keep API keys and project responses out of public issue reports and committed logs.

Hosted MCP exposes the same recovery steps through list_projects, get_project_status, and get_project_download; see the agent workflow. The CLI can list, inspect, and download an existing project without running djass generate again. Once you have the ZIP, continue with local development.

This section describes the hosted Djass implementation checked October 26, 2026, not your generated application's API. The general asynchronous request-reply pattern explains why durable job IDs matter; its optional idempotency-key mechanism is not a feature offered by this API.


6) Common failure cases (with real payload shapes)

Missing/invalid auth (401)

{
  "error": {
    "code": "auth_required",
    "category": "auth",
    "message": "Authentication required.",
    "retryable": false,
    "details": {}
  }
}

Missing scope (403)

{
  "error": {
    "code": "insufficient_scope",
    "category": "auth",
    "message": "API key is missing required scope: projects:create",
    "retryable": false,
    "details": {
      "required_scope": "projects:create"
    }
  }
}

Invalid slug (400)

{
  "error": {
    "code": "invalid_project_slug",
    "category": "validation",
    "message": "project_slug must contain letters or numbers.",
    "retryable": false,
    "details": {
      "field": "project_slug"
    }
  }
}

Quota exceeded (429)

{
  "error": {
    "code": "quota_exceeded",
    "category": "quota",
    "message": "Project quota exceeded for this API identity.",
    "retryable": false,
    "details": {
      "quota": 200,
      "retry_guidance": "Delete old projects or request limit bump."
    }
  }
}

Temporary queue failure (503, retryable)

Reconcile the existing project before another create request; a 503 does not guarantee that no row was created. Use the recovery checklist above.

{
  "error": {
    "code": "retryable_error",
    "category": "retryable",
    "message": "Temporary failure while queueing project generation.",
    "retryable": true,
    "details": {
      "retry_guidance": "Retry with exponential backoff."
    }
  }
}

Not found (404)

{
  "error": {
    "code": "project_not_found",
    "category": "validation",
    "message": "Project not found.",
    "retryable": false,
    "details": {
      "project_id": 999999
    }
  }
}

Artifact not ready (409, retryable)

{
  "error": {
    "code": "artifact_not_ready",
    "category": "retryable",
    "message": "Project artifact is not ready yet.",
    "retryable": true,
    "details": {
      "project_id": 123,
      "status": "generating",
      "retry_guidance": "Poll the status endpoint until artifact_ready is true."
    }
  }
}

7) Implementation references

This API reference is aligned with backend implementation and tests: - endpoint logic: apps/api/views.py - schema definitions: apps/api/schemas.py - auth parsing/scoping: apps/api/auth.py, apps/api/utils.py - project endpoint tests: apps/api/test_project_endpoints.py - API key authorization tests: apps/api/test_api_key_authorization.py - artifact download tests: apps/api/test_artifact_downloads.py - generator options tests: apps/api/test_project_options.py

The API records successful project operations, invalid credentials, scope denials, and artifact-download outcomes in ProjectAPIAuditLog. The Django audit log design guide explains why these action records are separate from model history and how to choose transaction, privacy, retention, and failure policies for your own product.

Local execution note: - running API tests in this environment requires PostgreSQL with pgvector migration support (CREATE EXTENSION vector) - sqlite fallback test run fails by design on that migration


8) Known limitations / TODO

  1. No idempotency key on create: repeated POST /projects can create duplicates. Use the recovery checklist after a lost response.
  2. No callback/webhook for completion: clients must poll /status.
  3. Legacy query-string auth remains enabled for compatibility; should eventually be deprecated for security hygiene.
  4. No server-provided request ID in response body for cross-system tracing.