Organizations API

The Organizations API allows you to manage organization invitations and memberships.

Base URL

https://dreamsolve.ai/api/v1

Authentication

All endpoints require authentication via the x-api-key header. See the API Overview for details.

---

List Invitations

List all invitations for an organization.

GET /api/v1/organizations/:organizationId/invitations

Path Parameters

Parameter	Type	Description
organizationId	string	The organization ID

Requirements

• User must be a member of the organization

Response

{
  "invitations": [
    {
      "id": "inv_123",
      "invitee_email": "user@example.com",
      "status": "pending",
      "role_id": "role_456",
      "created_at": "2024-01-15T10:00:00Z",
      "expires_at": "2024-01-22T10:00:00Z"
    }
  ]
}

---

Create Invitation

Create a new organization invitation.

POST /api/v1/organizations/:organizationId/invitations

Path Parameters

Parameter	Type	Description
organizationId	string	The organization ID

Requirements

• User must be an owner of the organization

Request Body

{
  "inviteeEmail": "newuser@example.com",
  "roleId": "role_456"
}

Field	Type	Required	Description
inviteeEmail	string	Yes	Email address of the person to invite
roleId	string	Yes	Role ID to assign to the invitee

Response

{
  "invitation": {
    "id": "inv_124",
    "invitee_email": "newuser@example.com",
    "status": "pending",
    "role_id": "role_456",
    "created_at": "2024-01-15T10:00:00Z",
    "expires_at": "2024-01-22T10:00:00Z"
  }
}

Status Code: 201 Created

---

Cancel Invitation

Cancel a pending invitation.

DELETE /api/v1/organizations/:organizationId/invitations/:invitationId

Path Parameters

Parameter	Type	Description
organizationId	string	The organization ID
invitationId	string	The invitation ID

Requirements

• User must be an owner of the organization

Response

{
  "message": "Invitation cancelled successfully"
}

---

Invitation Status Values

Status	Description
pending	Invitation has been sent, awaiting acceptance
accepted	Invitation was accepted
expired	Invitation has expired
cancelled	Invitation was cancelled

---

Organization Roles

Common organization roles:

Role	Description
owner	Full administrative access
admin	Administrative access (cannot delete org)
member	Standard member access
viewer	Read-only access

---

Error Responses

Status Code	Description
400	Bad Request - Missing required fields
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Organization or invitation not found
500	Internal Server Error

Example Error Responses

{
  "error": "inviteeEmail is required"
}

{
  "error": "Only organization owners can create invitations"
}

{
  "error": "Failed to create invitation. You may not have permission, or the user may already be a member."
}

---

Example Usage

List organization invitations

curl -X GET \
  -H "x-api-key: YOUR_API_KEY" \
  https://dreamsolve.ai/api/v1/organizations/org_123/invitations

Invite a new member

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inviteeEmail": "colleague@example.com",
    "roleId": "role_member"
  }' \
  https://dreamsolve.ai/api/v1/organizations/org_123/invitations