API reference

Portal: resources, groups, tags and dashboards

Every resource of an organization in one list, resource groups and tags, each resource's activity and access, your favourite services and recent resources, and dashboards.

GET/v1/orgs/:orgId/portal/resources

Every resource of the org you may read, of every kind (Serverless App Services, databases, buckets, domains, repositories, agents), with its resource group and tags. q keeps those with every word in their name, details, id or tags; kind, group (a resource group id, or none) and tag (key or key=value) filter; limit caps the list (default 500). total and counts (by kind) are of every resource you may read, before filters.

Auth: A person's token or an API key, as Authorization: Bearer.

Path parameters

orgId
Organization id (org_…).

Query parameters

qstring
Up to 200 characters.
kind"project" | "database" | "bucket" | "domain" | "repository" | "agent"
groupstring
Up to 64 characters.
tagstring
Up to 330 characters.
limitinteger
Default 500. 1–500. Coerced from a string.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/resources' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  resources: {
    kind: "project" | "repository" | "agent" | "database" | "bucket" | "domain"
    id: string
    name: string
    detail?: string
    location?: string
    region?: string
    projectId?: string
    groupId?: string
    tags: {
      key: string
      value: string
    }[]
    status?: string
    createdAt?: number
    updatedAt?: number
  }[]
  total: number
  counts: {
    project?: number
    repository?: number
    agent?: number
    database?: number
    bucket?: number
    domain?: number
  }
}

GET/v1/orgs/:orgId/portal/resources/:kind/:ref

One resource with its resource group and tags.

Auth: A person's token or an API key, as Authorization: Bearer.
Scopes: projects:read (for a Serverless App Service (project)), resources:read (for a database or bucket), domains:read (for a domain), git:read (for a repository), agents:read (for an agent)

Path parameters

orgId
Organization id (org_…).
kind
What the resource is: project (a Serverless App Service), database, bucket, domain, repository or agent; under vehicles the kind of schedule, charge or precondition.
ref
The resource: its id (prj_…, res_…, dev_…), or a domain's hostname.

Errors

404Unknown kind of resource.
404Resource not found.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/resources/{kind}/{ref}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  resource: {
    kind: "project" | "repository" | "agent" | "database" | "bucket" | "domain"
    id: string
    name: string
    detail?: string
    location?: string
    region?: string
    projectId?: string
    groupId?: string
    tags: {
      key: string
      value: string
    }[]
    status?: string
    createdAt?: number
    updatedAt?: number
  }
}

PUT/v1/orgs/:orgId/portal/resources/:kind/:ref

Sets a resource's resource group (groupId, or null for none) and its tags (tags: up to 20 { key, value }, keys unique; replaces them all). Needs the right to change that resource.

Auth: A person's token or an API key, as Authorization: Bearer.
Scopes: projects:read (for a Serverless App Service (project)), resources:read (for a database or bucket), domains:read (for a domain), git:read (for a repository), agents:read (for an agent), projects:write (for a Serverless App Service (project)), resources:write (for a database or bucket), domains:write (for a domain), git:write (for a repository)

Path parameters

orgId
Organization id (org_…).
kind
What the resource is: project (a Serverless App Service), database, bucket, domain, repository or agent; under vehicles the kind of schedule, charge or precondition.
ref
The resource: its id (prj_…, res_…, dev_…), or a domain's hostname.

Request body

groupIdstringor null
Up to 64 characters.
tagsobject[]
Up to 20 items.
tags[].keystringrequired
Up to 64 characters.
tags[].valuestringrequired
Up to 256 characters.

Errors

400Agents have no tags or groups.
400Resource group not found.
400Tag keys use letters, numbers, spaces and _ . : / = + - @, up to 64 characters, each once.
404Unknown kind of resource.
404Resource not found.

curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/resources/{kind}/{ref}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "groupId": "<groupId>",
    "tags": [
      {
        "key": "example",
        "value": "example"
      }
    ]
  }'

Send it from this page with your session or a key.

Response 200

{
  groupId: null | string
  tags: {
    key: string
    value: string
  }[]
}

GET/v1/orgs/:orgId/portal/resources/:kind/:ref/activity

What happened to a resource, newest first: its entries in the org's audit log, filtered like the log (action, actor) and paged (cursor, limit). Readable by those who may read the resource.

Auth: A person's token or an API key, as Authorization: Bearer.
Scopes: projects:read (for a Serverless App Service (project)), resources:read (for a database or bucket), domains:read (for a domain), git:read (for a repository), agents:read (for an agent)

Path parameters

orgId
Organization id (org_…).
kind
What the resource is: project (a Serverless App Service), database, bucket, domain, repository or agent; under vehicles the kind of schedule, charge or precondition.
ref
The resource: its id (prj_…, res_…, dev_…), or a domain's hostname.

Query parameters

cursorstring
Up to 4,096 characters.
actionstring
Matches ^[a-z_]{1,32}(\.[a-z_]{1,32})?$.
actorstring
1–512 characters.
limitinteger
Default 50. 1–100. Coerced from a string.

Errors

400Invalid cursor
404Unknown kind of resource.
404Resource not found.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/resources/{kind}/{ref}/activity' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  events: {
    eventId: string
    orgId: string
    action: string
    actor: {
      type: "user" | "key" | "device" | "system"
      id: string
      label?: string
    }
    target: {
      type: string
      id: string
      label?: string
    }
    metadata?: {
      [key: string]: unknown
    }
    ip?: string
    userAgent?: string
    createdAt: number
  }[]
  cursor: null | string
  retentionDays?: number
}

GET/v1/orgs/:orgId/portal/resources/:kind/:ref/access

Who can reach a resource: each member, their role and what that role lets them do with it (manage, change or read), and the groups whose grants widen access to a Serverless App Service or a repository. Roles are changed in Tenant.

Auth: A person's token or an API key, as Authorization: Bearer.
Scopes: members:read, projects:read (for a Serverless App Service (project)), resources:read (for a database or bucket), domains:read (for a domain), git:read (for a repository), agents:read (for an agent)

Path parameters

orgId
Organization id (org_…).
kind
What the resource is: project (a Serverless App Service), database, bucket, domain, repository or agent; under vehicles the kind of schedule, charge or precondition.
ref
The resource: its id (prj_…, res_…, dev_…), or a domain's hostname.

Errors

404Unknown kind of resource.
404Resource not found.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/resources/{kind}/{ref}/access' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  members: {
    userId: string
    name?: string
    email?: string
    role: "owner" | "admin" | "developer" | "viewer"
    access: string
  }[]
  groups: {
    teamId: string
    name: string
    access: string
  }[]
}

GET/v1/orgs/:orgId/portal/groups

The org's resource groups.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: org:read

Path parameters

orgId
Organization id (org_…).

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/groups' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  groups: {
    groupId: string
    name: string
    description?: string
    createdAt?: number
  }[]
}

POST/v1/orgs/:orgId/portal/groups

Creates a resource group (name, optional description). Needs resources:write.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: resources:write

Path parameters

orgId
Organization id (org_…).

Request body

namestringrequired
1–64 characters. Trimmed.
descriptionstring
Up to 256 characters. Trimmed.

Errors

400An organization has at most 200 resource groups.
409A resource group with this name exists.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/groups' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example"
  }'

Send it from this page with your session or a key.

Response 201

{
  group: {
    groupId: string
    name: string
    description?: string
    createdAt?: number
  }
}

PATCH/v1/orgs/:orgId/portal/groups/:resourceGroupId

Renames a resource group or changes its description. Needs resources:write.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: resources:write

Path parameters

orgId
Organization id (org_…).
resourceGroupId
Resource group id (rgp_…).

Request body

namestring
1–64 characters. Trimmed.
descriptionstring
Up to 256 characters. Trimmed.

Errors

404Resource group not found.
409A resource group with this name exists.

curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/groups/{resourceGroupId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example",
    "description": "example"
  }'

Send it from this page with your session or a key.

Response 200

{
  group: {
    groupId: string
    name: string
    description?: string
  }
}

DELETE/v1/orgs/:orgId/portal/groups/:resourceGroupId

Deletes a resource group; its resources stay, outside any group. Needs resources:write.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: resources:write

Path parameters

orgId
Organization id (org_…).
resourceGroupId
Resource group id (rgp_…).

Errors

404Resource group not found.

curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/groups/{resourceGroupId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  ok: true
}

GET/v1/orgs/:orgId/portal/me

Your portal in this org: favourite services in order (null: the defaults), recent resources and the dashboard Dashboard opens. People only.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: org:read

Path parameters

orgId
Organization id (org_…).

Errors

403The portal's preferences and dashboards belong to people.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/me' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  favourites: null | string[]
  recent: {
    kind: "project" | "repository" | "agent" | "database" | "bucket" | "domain"
    id: string
    name: string
    at: number
  }[]
  dashboardId: null | string
}

PUT/v1/orgs/:orgId/portal/me

Saves your favourite services (favourites: service keys in order, null for the defaults) or the dashboard Dashboard opens (dashboardId).

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: org:read

Path parameters

orgId
Organization id (org_…).

Request body

favouritesstring[]or null
Up to 40 items. Each up to 40 characters.
dashboardIdstringor null
Up to 64 characters.

Errors

403The portal's preferences and dashboards belong to people.

curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/me' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "favourites": [
      "example"
    ],
    "dashboardId": "<dashboardId>"
  }'

Send it from this page with your session or a key.

Response 200

{
  favourites: null | string[]
  recent: {
    kind: "project" | "repository" | "agent" | "database" | "bucket" | "domain"
    id: string
    name: string
    at: number
  }[]
  dashboardId: null | string
}

POST/v1/orgs/:orgId/portal/me/recent

Records that you opened a resource (kind, ref), for Recent.

Auth: A person's token or an API key, as Authorization: Bearer.
Scopes: projects:read (for a Serverless App Service (project)), resources:read (for a database or bucket), domains:read (for a domain), git:read (for a repository), agents:read (for an agent)

Path parameters

orgId
Organization id (org_…).

Request body

kind"project" | "database" | "bucket" | "domain" | "repository" | "agent"required
refstringrequired
1–260 characters.

Errors

403The portal's preferences and dashboards belong to people.
404Resource not found.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/me/recent' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "project",
    "ref": "example"
  }'

Send it from this page with your session or a key.

Response 200

{
  recent: {
    kind: "project" | "repository" | "agent" | "database" | "bucket" | "domain"
    id: string
    name: string
    at: number
  }[]
}

GET/v1/orgs/:orgId/portal/dashboards

Dashboards you can open: yours and those shared with the organization (without their tiles).

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: org:read

Path parameters

orgId
Organization id (org_…).

Errors

403The portal's preferences and dashboards belong to people.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/dashboards' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  dashboards: {
    tiles?: {
      id: string
      type: "resource" | "link" | "deployments" | "recent" | "note" | "traffic" | "services"
      x: number
      y: number
      w: number
      h: number
      config: {
        [key: string]: string
      }
    }[]
    dashboardId: string
    name: string
    ownerId: string
    shared: boolean
    updatedAt?: number
  }[]
}

POST/v1/orgs/:orgId/portal/dashboards

Creates a dashboard (name, optional shared and tiles); yours alone unless shared.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: org:read

Path parameters

orgId
Organization id (org_…).

Request body

namestringrequired
1–80 characters. Trimmed.
sharedboolean
tilesany JSON[]
Up to 60 items.

Errors

400You have 50 dashboards here already.
403The portal's preferences and dashboards belong to people.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/dashboards' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example"
  }'

Send it from this page with your session or a key.

Response 201

{
  dashboard: {
    tiles?: {
      id: string
      type: "resource" | "link" | "deployments" | "recent" | "note" | "traffic" | "services"
      x: number
      y: number
      w: number
      h: number
      config: {
        [key: string]: string
      }
    }[]
    dashboardId: string
    name: string
    ownerId: string
    shared: boolean
    updatedAt?: number
  }
}

GET/v1/orgs/:orgId/portal/dashboards/:dashboardId

A dashboard with its tiles.

Auth: A person's token or an API key, as Authorization: Bearer.

Path parameters

orgId
Organization id (org_…).
dashboardId
Dashboard id: an issue dashboard (dsh_…) or a Cloud portal dashboard (pdb_…).

Errors

403The portal's preferences and dashboards belong to people.
404Dashboard not found.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/dashboards/{dashboardId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  dashboard: {
    canChange?: boolean
    tiles?: {
      id: string
      type: "resource" | "link" | "deployments" | "recent" | "note" | "traffic" | "services"
      x: number
      y: number
      w: number
      h: number
      config: {
        [key: string]: string
      }
    }[]
    dashboardId: string
    name: string
    ownerId: string
    shared: boolean
    updatedAt?: number
  }
}

PUT/v1/orgs/:orgId/portal/dashboards/:dashboardId

Changes a dashboard: name, shared (owners only) and tiles (replaced; positions are compacted).

Auth: A person's token or an API key, as Authorization: Bearer.

Path parameters

orgId
Organization id (org_…).
dashboardId
Dashboard id: an issue dashboard (dsh_…) or a Cloud portal dashboard (pdb_…).

Request body

namestring
1–80 characters. Trimmed.
sharedboolean
tilesany JSON[]
Up to 60 items.

Errors

403The portal's preferences and dashboards belong to people.
403Only its owner changes this dashboard.
403Only its owner shares or unshares a dashboard.
404Dashboard not found.

curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/dashboards/{dashboardId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example",
    "shared": true,
    "tiles": [
      {}
    ]
  }'

Send it from this page with your session or a key.

Response 200

{
  dashboard: {
    canChange: true
    tiles?: {
      id: string
      type: "resource" | "link" | "deployments" | "recent" | "note" | "traffic" | "services"
      x: number
      y: number
      w: number
      h: number
      config: {
        [key: string]: string
      }
    }[]
    dashboardId: string
    name: string
    ownerId: string
    shared: boolean
    updatedAt?: number
  }
}

DELETE/v1/orgs/:orgId/portal/dashboards/:dashboardId

Deletes a dashboard (its owner, or for a shared one those who manage the organization).

Auth: A person's token or an API key, as Authorization: Bearer.

Path parameters

orgId
Organization id (org_…).
dashboardId
Dashboard id: an issue dashboard (dsh_…) or a Cloud portal dashboard (pdb_…).

Errors

403The portal's preferences and dashboards belong to people.
403Only its owner deletes this dashboard.
404Dashboard not found.

curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/portal/dashboards/{dashboardId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  ok: true
}