One API. Five focused services.

Architecture

A capability-first API

Start by asking the platform what is available. The catalog reports enabled services, current blockers, required connections, access levels, and exact operations. Clients follow advertised operations instead of guessing routes.

1. 01DiscoverAsk NoxConnect which services are available to this organization. The response lists what each service can do and the exact operations clients may call.
2. 02InspectCheck whether the chosen service is enabled and healthy. Setup reports anything still needed, such as a GitHub or Slack connection.
3. 03ConnectStart a provider connection through the API. A person opens the returned link and approves access in GitHub or Slack; the client never receives the provider credential.
4. 04ConfigureRead the current settings and keep the returned revision. Send it back with a change so newer work cannot be overwritten accidentally.
5. 05OperateCall only the operations advertised for the selected capability. Check the access and change-safety labels before every write or destructive action.

Quickstart

Discover your workspace

This request shape is for first-party Nox clients and user-approved automation whose secure runtime has received a Nox GitHub App OAuth access token. The hosted API does not currently issue third-party client credentials.

curl https://app.noxhere.com/api/v1/services \
  --header "Authorization: Bearer $GITHUB_TOKEN" \
  --header "X-Org: your-organization"

{
  "apiVersion": 1,
  "organization": { "login": "your-organization" },
  "canConfigure": true,
  "services": [
    {
      "id": "noxfeed",
      "enabled": true,
      "setup": { "state": "ready" },
      "capabilities": [/* operations live here */]
    }
  ]
}

Authentication

Two headers define the caller

Operations advertise member, admin, public, or ingest_key authentication. Setup mutations and organization configuration require admin access. OAuth start operations may return a temporary userAction.url; do not log it or fetch it with an automated client. Give it to a human, then poll setup no more than once every five seconds.

Service catalog

Clear ownership at every boundary

NoxConnect owns shared infrastructure. Each product owns the resources and behavior unique to its job.

Control plane

The same shape for every service

Replace {service} with noxconnect, noxticket, noxfeed, noxspot, or noxcue.

Safe configuration

Read, revise, then write

Configuration updates use optimistic concurrency. Read the document, retain its ETag, then include that value in If-Match. A stale client receives 412 instead of overwriting newer work.

# 1. Read the current config and response ETag
curl -i https://app.noxhere.com/api/v1/services/noxfeed/config \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-Org: your-organization"

# 2. Patch only owned fields using that revision
curl -X PATCH https://app.noxhere.com/api/v1/services/noxfeed/config \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-Org: your-organization" \
  -H 'If-Match: "current-revision"' \
  -H "Content-Type: application/json" \
  --data '{"projectScope":null}'

projectScope: null means all projects. Otherwise supply an active project ID returned by GET /api/projects; arbitrary strings are rejected.

Operations

Follow the advertised contract

Every capability contains an operations array. Each operation declares a stable ID, HTTP method, path, authentication mode, and description. The catalog and OpenAPI document are tested for alignment.

{
  "id": "patch_feed_config",
  "method": "PATCH",
  "path": "/api/v1/services/noxfeed/config",
  "authentication": "admin",
  "description": "Update project scope or release-notes prompt with If-Match."
}

The reference below is rendered directly from OpenAPI 3.1, so routes, methods, access levels, server overrides, and change-safety labels do not have to be copied into this page by hand. Older compatibility endpoints may still expose loosely typed response bodies; those are labelled as legacy JSON in the schema.

Errors

One predictable v1 envelope

{
  "apiVersion": 1,
  "error": {
    "code": "revision_conflict",
    "message": "Settings changed concurrently; fetch config and retry",
    "details": { "currentRevision": "…" }
  }
}

All /api/v1/* errors, including authentication and organization failures raised before a handler runs, use this envelope. Compatibility routes under /api/* may still return { "error": "message" }.

Safety model

Defaults designed for automation