Organization¶

Create organizations, configure monetization add-ons, run gateway analytics queries, and list partner organizations.

Authentication

All methods require a valid Platform API key in the x-yappes-key header.

Base URL

Substitute the sample host https://platformapi.enterprise-xyz.com with the Platform API URL configured for your Yappes organization, since the host value changes depending on the organization and deployment setup.

REST Resources¶

Resource	Methods
organizations	create, setAddons
organizations.environments.queries	create, getResult
organizations.partners	list, getByEmail

Resource: organizations¶

Organization lifecycle and add-on configuration.

Platform API — Create Organization¶

Creates a new external organization. Only organizationName is accepted from the client; description is sent as empty and type is forced to external.

HTTP request¶

POST https://platformapi.enterprise-xyz.com/v1/organizations/create

Path parameters¶

None.

Query parameters¶

None.

Request body¶

{
  "organizationName": "My Partner Org"
}

Field	Type	Required	Description
`organizationName`	string	Yes	Name for the new organization.

Response body¶

If successful, the response body contains the created organization details.

Errors¶

HTTP status	Condition
`400`	Missing `organizationName`.
`502`	Service unreachable or returned an error.

Authorization¶

Requires a valid x-yappes-key header.

Method: organizations.setAddons¶

Enables or disables the monetization add-on for an organization.

HTTP request¶

POST https://platformapi.enterprise-xyz.com/v1/organizations/{orgReferenceId}:setAddons

The colon in :setAddons is part of the path (custom method syntax).

Path parameters¶

Parameter	Type	Description
`orgReferenceId`	string	Required. Organization reference. Resolved to an internal `organizationId`.

Query parameters¶

None.

Request body¶

{
  "addonsConfig": {
    "monetizationConfig": {
      "enabled": true
    }
  }
}

Field	Type	Required	Description
`addonsConfig.monetizationConfig.enabled`	boolean	Yes	Must be `true` or `false`.

Response body¶

If successful (200), the response body is:

{
  "name": "organizations/yappes-organization/operations/<uuid>",
  "metadata": {
    "@type": "type.googleapis.com/yappes.platform.v1.OperationMetadata",
    "operationType": "UPDATE",
    "targetResourceName": "organizations/yappes-organization",
    "state": "IN_PROGRESS"
  }
}

Errors¶

HTTP status	Condition
`400`	`enabled` is missing or not a boolean.
`404`	Organization not found.
`503`	Service temporarily unavailable.

Authorization¶

Requires a valid x-yappes-key header.

Resource: organizations.environments.queries¶

Environment-scoped analytics queries against gateway traffic data.

Platform API — Gateway Transaction Logs API¶

Runs an analytics query against gateway traffic data and returns a query descriptor.

HTTP request¶

POST https://platformapi.enterprise-xyz.com/v1/organizations/{orgReferenceId}/environments/{envName}/queries

Path parameters¶

Parameter	Type	Description
`orgReferenceId`	string	Required. Organization reference.
`envName`	string	Required. Environment name (stored on the query record).

Query parameters¶

None.

Request body¶

{
  "timeRange": "2026-06-01T00:00:00Z/2026-06-30T23:59:59Z",
  "metrics": [
    { "name": "message_count", "function": "SUM" }
  ],
  "dimensions": [
    { "name": "apiproxy" }
  ],
  "groupByTimeUnit": "day",
  "limit": 1000
}

Field	Type	Required	Description
`timeRange`	string	Yes	`<startISO>/<endISO>` date range.
`metrics`	array	Yes	At least one metric. Allowed names: `message_count`, `response_processing_time`, `total_response_time`, `target_response_time`, `request_processing_latency`, `response_processing_latency`. Each item may include `function`: `SUM`, `AVG`, `MIN`, `MAX`, or `COUNT` (default `SUM`).
`dimensions`	array	No	Group-by dimensions. Allowed names: `apiproxy`, `proxy`, `client_id`, `developer_email`, `request_uri`, `request_path`, `response_status_code`, `request_verb`.
`groupByTimeUnit`	string	No	Time bucket unit: `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, or `year`.
`limit`	integer	No	Max rows. Default `10000`, maximum `100000`.

Response body¶

If successful (201), the response body is:

{
  "name": "organizations/yappes-organization/environments/prod/queries/<uuid>",
  "state": "enqueued",
  "created": "1717424600000",
  "updated": "1717424600000"
}

Errors¶

HTTP status	Condition
`400`	Invalid or missing `timeRange`, or no supported metrics.
`404`	Organization not found.
`503`	Service temporarily unavailable.

Authorization¶

Requires a valid x-yappes-key header.

Platform API — Gateway Transaction Logs API (Get Result)¶

Fetches the result of a previously created analytics query.

HTTP request¶

GET https://platformapi.enterprise-xyz.com/v1/organizations/{orgReferenceId}/environments/{envName}/queries/{queryId}/result

Path parameters¶

Parameter	Type	Description
`orgReferenceId`	string	Required. Organization reference.
`envName`	string	Required. Environment name.
`queryId`	string	Required. Query id returned when the query was created.

Query parameters¶

None.

Request body¶

The request body must be empty.

Response body¶

If successful (200), the response body is:

{
  "code": 200,
  "name": "organizations/yappes-organization/environments/prod/queries/<uuid>",
  "state": "completed",
  "result": {
    "rows": [
      {
        "apiproxy": "API-F0F6C9F1",
        "message_count": 42,
        "timestamp": 1717200000000
      }
    ]
  }
}

When groupByTimeUnit is set, each row may include a timestamp field (epoch ms).

Errors¶

HTTP status	Condition
`404`	Organization or query not found.
`503`	Service temporarily unavailable.

Authorization¶

Requires a valid x-yappes-key header.

Resource: organizations.partners¶

External (partner) organization discovery.

Method: organizations.partners.list¶

Lists all organizations with type = external, enriched with userCount, apiCount, and billingDetails.

HTTP request¶

GET https://platformapi.enterprise-xyz.com/v1/organizations/partner/all

Path parameters¶

None.

Query parameters¶

None.

Request body¶

The request body must be empty.

Response body¶

If successful (200), the response body is:

{
  "code": 200,
  "status": "OK",
  "data": [
    {
      "organizationId": "ORG-9C2D5B74",
      "organizationName": "my-partner-org",
      "type": "external",
      "description": "",
      "gstNumber": null,
      "modifiedDateTime": "2026-06-04T10:15:00.000Z",
      "userCount": 3,
      "apiCount": 5,
      "billingDetails": {}
    }
  ]
}

Returns "data": [] when no external organizations exist.

Authorization¶

Requires a valid x-yappes-key header.

Platform API — Get Partner Organizations by Email¶

Lists all external organizations that a given email is a member of, enriched with userCount, apiCount, and billingDetails.

HTTP request¶

GET https://platformapi.enterprise-xyz.com/v1/organizations/partner/{emailId}

Path parameters¶

Parameter	Type	Description
`emailId`	string	Required. Member email address (URL-encoded if needed).

Query parameters¶

None.

Request body¶

The request body must be empty.

Response body¶

If successful (200), the response body has the same shape as partners list.

Returns "data": [] when the email is unknown or the user is not a member of any external organization.

Authorization¶

Requires a valid x-yappes-key header.

Method index¶

#	HTTP	Path
1	POST	`/v1/organizations/{orgReferenceId}:setAddons`
2	POST	`/v1/organizations/{orgReferenceId}/environments/{envName}/queries`
3	GET	`/v1/organizations/{orgReferenceId}/environments/{envName}/queries/{queryId}/result`
4	POST	`/v1/organizations/create`
5	GET	`/v1/organizations/partner/all`
6	GET	`/v1/organizations/partner/{emailId}`