Core API — Teams Module

Praemunio API • Version 1 • Developer Documentation

The Teams module enables organizations to manage collaborative units, control user access via granular permission templates, manage pending invitations, and monitor audit trails.

Key	Value
Base URL	`https://api.praemunio.org/api/v1`
Format	JSON (`Content-Type: application/json`)
Authentication	Bearer Token (`Authorization: Bearer <access_token>`)
Required Scopes	`teams:read`, `teams:write`, `teams:delete`

Overview & Permission Model

Team Management Endpoints

Member & Invitation Endpoints

POST /teams/members/add

GET /teams/members/invitations

GET /teams/members

DELETE /teams/members/remove

Permission Templates & Access Control

GET /teams/permissions

GET /teams/permissions/templates

POST /teams/permissions/templates/create

PUT /teams/permissions/templates/update

DELETE /teams/permissions/templates/delete

Dashboard & Audit Logs

GET /teams/dashboard

GET /teams/logs

Client Integration Example

Error Handling Reference

1. Overview & Permission Model

A Team is the primary boundary for access control and collaborative resource sharing in Praemunio. Teams support two operational types (individual or legal_entity) and support custom permission templates alongside fine-grained workspace and folder assignments.

2. Team Management Endpoints

POST /teams/create

Creates a new team under the caller's account.

Scope Required: teams:write

HTTP Code: 201 Created

Request Body

{
  "name": "Finance & Legal Operations",
  "description": "Cross-functional team for contract anchoring and compliance",
  "type": "legal_entity"
}

Field	Type	Required	Validation / Description
`name`	string	Yes	Min 2 characters
`description`	string	No	Optional team summary
`type`	string	Yes	Allowed values: `'individual'`, `'legal_entity'`

Response (`201 Created`)

{
  "success": true,
  "message": "Team created successfully",
  "result": {
    "id": "e4a9d1b0-7c2e-4f3a-8b1d-9e0f2a4c6b8d",
    "name": "Finance & Legal Operations",
    "description": "Cross-functional team for contract anchoring and compliance",
    "type": "legal_entity",
    "ownerAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "createdAt": "2026-09-30T10:15:00.000Z",
    "updatedAt": "2026-09-30T10:15:00.000Z"
  },
  "errors": null,
  "except": null
}

GET /teams

Retrieves all teams owned by or accessible to the caller's account.

Scope Required: teams:read

HTTP Code: 200 OK

Response (`200 OK`)

{
  "success": true,
  "message": "Teams retrieved successfully",
  "result": [
    {
      "id": "e4a9d1b0-7c2e-4f3a-8b1d-9e0f2a4c6b8d",
      "name": "Finance & Legal Operations",
      "type": "legal_entity",
      "memberCount": 5,
      "workspaceCount": 2,
      "createdAt": "2026-09-30T10:15:00.000Z"
    }
  ],
  "errors": null,
  "except": null
}

GET /teams/info

Fetches full detailed metadata for a specific team.

Scope Required: teams:read

HTTP Code: 200 OK

Query Parameter: team_id (UUIDv4 string, required)

cURL Example

Response (`200 OK`)

{
  "success": true,
  "message": "Team details retrieved successfully",
  "result": {
    "id": "e4a9d1b0-7c2e-4f3a-8b1d-9e0f2a4c6b8d",
    "name": "Finance & Legal Operations",
    "description": "Cross-functional team for contract anchoring",
    "type": "legal_entity",
    "ownerAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "workspaces": [
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
        "name": "Legal Workstation"
      }
    ],
    "members": 5,
    "createdAt": "2026-09-30T10:15:00.000Z"
  },
  "errors": null,
  "except": null
}

PUT /teams/update

Updates team information.

Scope Required: teams:write

HTTP Code: 200 OK

Request Body

{
  "id": "e4a9d1b0-7c2e-4f3a-8b1d-9e0f2a4c6b8d",
  "name": "Global Legal Operations",
  "description": "Updated global legal team"
}

Response (`200 OK`)

{
  "success": true,
  "message": "Team updated successfully",
  "result": {
    "id": "e4a9d1b0-7c2e-4f3a-8b1d-9e0f2a4c6b8d",
    "name": "Global Legal Operations",
    "description": "Updated global legal team",
    "type": "legal_entity",
    "updatedAt": "2026-09-30T10:30:00.000Z"
  },
  "errors": null,
  "except": null
}

DELETE /teams/delete

Deletes a team and revokes associated permissions.

Scope Required: teams:delete

HTTP Code: 204 No Content

Request Body

{
  "team_id": "e4a9d1b0-7c2e-4f3a-8b1d-9e0f2a4c6b8d"
}

3. Member & Invitation Endpoints

POST /teams/members/add

Invites a new member to a team with optional custom permission template and granular folder/workspace assignment.

Scope Required: teams:write

HTTP Code: 201 Created

Request Body

{
  "teamId": "e4a9d1b0-7c2e-4f3a-8b1d-9e0f2a4c6b8d",
  "email": "auditor@external-audit.com",
  "message": "Welcome to the Praemunio legal team",
  "permissionTemplateId": 3,
  "accessConfig": {
    "assignments": [
      {
        "workspace_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
        "folders": ["c3d4e5f6-a7b8-9012-cdef-345678901234"]
      }
    ]
  }
}

GET /teams/members/invitations

Lists invitations issued for a team with status filtering and pagination.

Scope Required: teams:read

HTTP Code: 200 OK

Query Parameters: team_id (required UUID), page (default 1), limit (default 20), status (optional: 'pending', 'accepted', 'cancelled')

Response (`200 OK`)

{
  "success": true,
  "message": "Invitations retrieved successfully",
  "result": {
    "data": [
      {
        "id": "f5a6b7c8-d9e0-1234-5678-90abcdef1234",
        "teamId": "e4a9d1b0-7c2e-4f3a-8b1d-9e0f2a4c6b8d",
        "email": "auditor@external-audit.com",
        "status": "pending",
        "createdAt": "2026-09-30T10:45:00.000Z"
      }
    ],
    "meta": {
      "total": 1,
      "per_page": 20,
      "current_page": 1,
      "last_page": 1,
      "first_page": 1,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false,
      "from": 1,
      "to": 1
    }
  },
  "errors": null,
  "except": null
}

GET /teams/members

Lists active members of a team.

Scope Required: teams:read

HTTP Code: 200 OK

Query Parameters: team_id (required UUID), page (default 1), limit (default 20)

DELETE /teams/members/remove

Removes a member from a team.

Scope Required: teams:write

HTTP Code: 204 No Content

Request Body

{
  "teamId": "e4a9d1b0-7c2e-4f3a-8b1d-9e0f2a4c6b8d",
  "memberAccountId": "d4e5f6a7-b8c9-0123-def0-123456789012",
  "reason": "Project assignment concluded"
}

4. Permission Templates & Access Control

GET /teams/permissions

Retrieves all permission actions and categories supported by Praemunio.

Scope Required: teams:read

GET /teams/permissions/templates

Lists existing custom permission templates available for the account.

Scope Required: teams:read

POST /teams/permissions/templates/create

Creates a reusable permission template.

Scope Required: teams:write

HTTP Code: 201 Created

Request Body

{
  "name": "Audit Only Template",
  "description": "Read-only access to documents and audit logs",
  "permissions": [
    {
      "category": "documents",
      "actions": ["read", "stream"]
    },
    {
      "category": "teams",
      "actions": ["read_logs"]
    }
  ]
}

5. Dashboard & Audit Logs

GET /teams/dashboard

Retrieves account-level dashboard statistics (active team count, member counts, storage metrics).

Scope Required: teams:read

GET /teams/logs

Retrieves audit logs for team activities (member invitations, permission updates, team modifications).

Scope Required: teams:read

Query Parameters: team_id (required UUID), page (default 1), limit (default 50)

6. Client Integration Example

7. Error Handling Reference

HTTP Status	Code	Cause	Action
`400 Bad Request`	`invalid_request`	Invalid UUID or missing required fields	Verify request schema
`403 Forbidden`	`insufficient_scopes`	Missing `teams:read` or `teams:write` scope	Update API Key scopes
`404 Not Found`	`team_not_found`	Specified `team_id` does not exist	Verify Team UUID
`409 Conflict`	`duplicate_member`	Member already invited or present in team	Check active invitations

Support

Questions? Visit docs.praemunio.io.

Teams

Core API — Teams Module#

Table of contents#

1. Overview & Permission Model#

2. Team Management Endpoints#

POST /teams/create#

Request Body#

Response (201 Created)#

GET /teams#

Response (200 OK)#

GET /teams/info#

cURL Example#

Response (200 OK)#

PUT /teams/update#

Request Body#

Response (200 OK)#

DELETE /teams/delete#

Request Body#

3. Member & Invitation Endpoints#

POST /teams/members/add#

Request Body#

GET /teams/members/invitations#

Response (200 OK)#

GET /teams/members#

DELETE /teams/members/remove#

Request Body#

4. Permission Templates & Access Control#

GET /teams/permissions#

GET /teams/permissions/templates#

POST /teams/permissions/templates/create#

Request Body#

5. Dashboard & Audit Logs#

GET /teams/dashboard#

GET /teams/logs#

6. Client Integration Example#

7. Error Handling Reference#

Support#

Core API — Teams Module

Table of contents

1. Overview & Permission Model

2. Team Management Endpoints

POST /teams/create

Request Body

Response (`201 Created`)

GET /teams

Response (`200 OK`)

GET /teams/info

cURL Example

Response (`200 OK`)

PUT /teams/update

Request Body

Response (`200 OK`)

DELETE /teams/delete

Request Body

3. Member & Invitation Endpoints

POST /teams/members/add

Request Body

GET /teams/members/invitations

Response (`200 OK`)

GET /teams/members

DELETE /teams/members/remove

Request Body

4. Permission Templates & Access Control

GET /teams/permissions

GET /teams/permissions/templates

POST /teams/permissions/templates/create

Request Body

5. Dashboard & Audit Logs

GET /teams/dashboard

GET /teams/logs

6. Client Integration Example

7. Error Handling Reference

Support