Skip to main content
Retrieve a list of organizations. You can filter organizations by state and user membership, and paginate through results.

​
Query Parameters

​
user_id
string
Filter organizations by user membership. Returns only organizations where the specified user is a member.
​
state
string
Filter organizations by state. Valid values are enabled or disabled.
​
page_size
integer
default:"50"
Number of organizations to return per page. Maximum value is typically 100.
​
page_num
integer
default:"1"
Page number for pagination. Starts at 1.

​
Response

​
organizations
array
Array of organization objects matching the filter criteria.
​
id
string
Unique identifier for the organization (UUID format).
​
name
string
Unique name/slug for the organization. Used in URLs and API calls.
​
title
string
Human-readable display name for the organization.
​
avatar
string
URL to the organization’s avatar image.
​
state
string
Current state of the organization. Either enabled or disabled.
​
metadata
object
Custom metadata associated with the organization. Can contain any valid JSON structure.
​
created_at
timestamp
Timestamp when the organization was created (RFC3339 format).
​
updated_at
timestamp
Timestamp when the organization was last updated (RFC3339 format).
curl -X GET 'https://api.frontier.example.com/v1beta1/organizations?page_size=10&state=enabled' \
  -H 'Authorization: Bearer <token>'

​
Response Example

{
  "organizations": [
    {
      "id": "9f256f86-d3c4-4a6e-b89a-1e9a23c5d78e",
      "name": "acme-corp",
      "title": "Acme Corporation",
      "avatar": "https://example.com/avatars/acme.png",
      "state": "enabled",
      "metadata": {
        "industry": "technology",
        "size": "enterprise"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-02-20T14:22:00Z"
    },
    {
      "id": "7b123d45-e6f7-8a9b-c0d1-2e3f4a5b6c7d",
      "name": "tech-startup",
      "title": "Tech Startup Inc",
      "avatar": "https://example.com/avatars/tech-startup.png",
      "state": "enabled",
      "metadata": {
        "industry": "saas",
        "founded": "2023"
      },
      "created_at": "2024-03-01T08:15:00Z",
      "updated_at": "2024-03-01T08:15:00Z"
    }
  ]
}

​
Error Responses

​
code
string
Error code indicating the type of error.
​
message
string
Human-readable error message.

​
Common Errors

  • 401 Unauthorized: Invalid or missing authentication token
  • 500 Internal Server Error: Server encountered an unexpected error

​
Notes

  • Results are returned in no guaranteed order unless sorting is implemented
  • Empty results return an empty array, not an error
  • Disabled organizations are only returned when explicitly filtering by state=disabled
  • User filtering requires the authenticated user to have appropriate permissions

Build docs developers (and LLMs) love

Get started for freeTalk to us