Public API

GeoJibe's public REST API is the contract for the CLI and Python client. Browser, CLI, and SDK clients all use the same /api/v1 handlers, ownership rules, and business logic.

The official CLI is geojibe:

pipx install geojibe

See Command-line client.

Dedicated and On-Site installations use this same API against the local user database. There is no central GeoJibe authentication service.

Environment variables

Reserve these names for the CLI and SDK:

export GEOJIBE_URL=https://<host>
export GEOJIBE_TOKEN=gjp_...

GEOJIBE_URL is the installation origin (no trailing slash). Do not hard-code a hosted GeoJibe URL — Dedicated and On-Site deployments use their own host.

Never put a token in a query string or URL path.

Authentication

Browser sessions continue to use the enciva_session cookie.

External clients authenticate with a Personal Access Token:

Authorization: Bearer $GEOJIBE_TOKEN

Tokens are created in Account → API Tokens. The full gjp_… value is shown once at creation. GeoJibe stores only a SHA-256 hash.

Session cookies are not accepted as Bearer credentials. A PAT cannot create or revoke other PATs; token management requires a browser session.

Expired and revoked tokens fail with HTTP 401. last_used_at is updated at most once per minute after a successful PAT authentication.

Authorization

A PAT belongs to one user and cannot see another user's Sources, Destinations, Jobs, or Recipes. Scopes only reduce that user's capabilities.

Scope	Access
account:read	Read the token owner's profile (GET /api/v1/auth/me)
sources:read	List and get Sources
sources:write	Create, update, delete, and test Sources
destinations:read	List and get Destinations
destinations:write	Create, update, delete, and test Destinations
jobs:read	List Jobs, get a Job, list Runs
jobs:write	Create, update, enable, disable, and delete Jobs
jobs:run	Run Now and retry a failed Run. Does not include jobs:read.
recipes:read	List and get Recipes
recipes:write	Create, update, and delete Recipes

There is no tokens:write scope in V1.

Jobs vs pipelines

Saved automation Jobs are the public resource. The browser UI still calls /api/v1/pipelines/… internally; those routes remain as compatibility aliases.

Public clients should use:

Action	Method	Path
List Jobs	GET	/api/v1/jobs
Get Job	GET	/api/v1/jobs/{id}
Create Job	POST	/api/v1/jobs
Update Job	PUT	/api/v1/jobs/{id}
Delete Job	DELETE	/api/v1/jobs/{id}
Run Job	POST	/api/v1/jobs/{id}/run
List Runs	GET	/api/v1/jobs/{id}/runs
Get Run	GET	/api/v1/jobs/{id}/runs/{runId}

GET /api/v1/jobs/{id} returns a saved Job when the id matches one the caller owns. Ephemeral Canvas conversion jobs remain on the same path for browser sessions; they are not the public Jobs resource.

Secrets

GET and list responses for Sources and Destinations never include passwords, secret keys, private keys, API tokens, or credential JSON. Use flags such as has_password and has_secret_key.

Errors

Failed requests return:

{
  "error": {
    "code": "forbidden",
    "message": "Token does not have jobs:run scope."
  }
}

Typical status codes: 200, 201, 204, 400, 401, 403, 404, 409, 422, 500.

Examples

Replace <host> with your installation. Do not paste real tokens into docs or shell history when you can avoid it.

List Sources

curl \
  -H "Authorization: Bearer $GEOJIBE_TOKEN" \
  "$GEOJIBE_URL/api/v1/sources"

List Destinations

curl \
  -H "Authorization: Bearer $GEOJIBE_TOKEN" \
  "$GEOJIBE_URL/api/v1/destinations"

List Jobs

curl \
  -H "Authorization: Bearer $GEOJIBE_TOKEN" \
  "$GEOJIBE_URL/api/v1/jobs"

Get Job

curl \
  -H "Authorization: Bearer $GEOJIBE_TOKEN" \
  "$GEOJIBE_URL/api/v1/jobs/<job-id>"

Run Job

curl \
  -X POST \
  -H "Authorization: Bearer $GEOJIBE_TOKEN" \
  "$GEOJIBE_URL/api/v1/jobs/<job-id>/run"

List Recipes

curl \
  -H "Authorization: Bearer $GEOJIBE_TOKEN" \
  "$GEOJIBE_URL/api/v1/recipes"