Apiable Platform API

{
  "openapi": "3.1.0",
  "info": {
    "title": " Apiable Platform API",
    "description": "\n## Introduction\n\nThe Apiable Platform API is a RESTful API that allows you to manage your portal, teams, users, and subscriptions. The API is designed to be simple and easy to use, with a focus on security and performance. \nThe Platform API is designed to be used by developers to build custom integrations and applications that interact with the Apiable Portal. The included endpoints allow you to manage, including, but not limited to, your portal products, plans, teams, users, and subscriptions.\n\n## Authentication\nThe authentication is done using a Bearer token, that must be included in all requests.\n \n## Errors\nThe API uses standard HTTP status codes to indicate the success or failure of a request. In case of an error, the response body will contain a JSON object with an error message.\n\n## Rate Limiting\n\n## Pagination and Filtering\nCalls that return multiple items will be paginated to 10 items by default. You can specify further pages with the `page` parameter. For most such resources, you can also set a custom page size up to 100 with the `size` parameter. Requests that return multiple items also include `search` parameter to filter the results.\n\n## Versioning\nThe API is versioned using the `X-API-Version` header. The API responses always with latest version, if not set otherwise.\n\n\n## Glossary of Terms\n### Product\nThe product object represents a high-level abstraction of your API products. It is used to group plans together and to provide a high-level overview of the product. A product can have multiple plans associated with it. Products are typically used to group plans together that are related to a specific API or service.\n\n### Plan\nThe plan object represents a subscription plan that can be associated with a product. A plan can have multiple APIs associated with it. Plans can be free or paid, and can have different pricing models.\n\n### Subscription \nThe subscription object represents a subscription to a plan. Subscriptions, both paid and free, are associated with a team, and a single user as the primary owner of the subscription. The owner of the subscription is considered to be the one responsible for the billing of the subscription.\nDepending on the permissions within a team, API key and billing information can be viewed managed by not just the subscription owner, but other members of the team as well.\n\n### Team\nThe team object represents a group of users that work together. A team can have multiple members and can be associated with a company. Teams are a way to group users together and manage permissions and roles within a group.\n\n### Company \nThe company object represents a group of teams. A company can have multiple teams associated with it. Companies are a way to manage multiple teams and users together. Companies do not have roles and permissions, nor are subscriptions shared between different teams under the same company.\n\n### User\nThe user object represents a user of the platform. A user can be a member of one or more teams and can have different roles and permissions within each team. Users can be invited to join a team, and can be assigned different roles and permissions within a team.\n\n### Invitation\nThe invitation object represents an invitation to join a team. Invitations are typically sent by team members to new users, and can be accepted or ignored by the invitee. Invitations can be sent to users that are not yet registered on the platform, and can be used to invite new users to join the platform and team of the inviter.\n\n### Webhook\nThe webhook object represents a webhook that can be used to receive notifications about events that occur on the platform. Webhooks can be used to trigger actions in external systems based on events that occur on the platform. Webhooks can be configured to send notifications for specific events, such as when a new subscription is created, or when a subscription is updated.\n\n\n### API Key Tutorial\n\nTo interact with the API, you will need to obtain an JWT Access Token. Follow these steps to obtain and use the Token:\n\n1. **Navigate to the Subscription Details Page**: Log in to your account and go to the Subscription Details page.\n2. **Locate the client_id/client_secret**: You will find it in the subscription details. The client_id and client_secret are unique to your account and will allow you to authenticate requests to the API.\n3. **Prefill the client_id and client_secret**: If you click the eye icon next to the client_id or client_secret, it will be revealed and automatically prefilled when you proceed to the documentation section.\n4. **Using the JWT Token**: Once you have your obtained your JWT token, you will need to include it in your request headers as follows:\n\n```\n'Authorization': 'Bearer YOUR_JWT_TOKEN_HERE'\n```\n\nMake sure to replace `YOUR_JWT_TOKEN_HERE` with the actual JWT token you obtained.",
    "contact": {
      "name": "Apiable Team",
      "url": "https://apiable.io",
      "email": "support@apiable.io"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "v2"
  },
  "servers": [
    {
      "url": "https://developer.apiable.io"
    }
  ],
  "tags": [
    {
      "name": "Companies",
      "description": "Companies, similar to teams are a way to group users together. Companies are a way to manage multiple teams and users together. An example being a company that has teams for different departments, such as backend and frontend development teams.Multiple teams can be part of the same company, and unlike teams, companies do not have roles and permissions, nor are subscriptions shared between different teams under the same company."
    },
    {
      "name": "Custom Properties",
      "description": "Custom properties are additional fields that can be used to store extra information about the subscription."
    },
    {
      "name": "Docs",
      "description": "Docs are a way to store documentation in the system. The documentation can be used to store API and Plan level API documentations in the system.A documentation entry is always associated with either plan directly, or with an API, which is associated with a plan.The only exception to this, is the Full API Reference, which is a special case, and is not associated with any plan. But with the portal itself."
    },
    {
      "name": "Files",
      "description": "Files are a way to store files in the system. All uploaded files are stored in an S3 bucket."
    },
    {
      "name": "Invitations",
      "description": "Invitations are a way to invite new users to join the platform and team of the inviter. Invitations are typically sent by team members to new users, and can be accepted or ignored by the invitee."
    },
    {
      "name": "Plans",
      "description": "Plans are a way to group APIs and their documentation."
    },
    {
      "name": "Products",
      "description": "Products are a high-level abstraction of your API products, they are used to group plans together and to provide a high level overview of the product."
    },
    {
      "name": "Serverinfo",
      "description": "Serverinfo is a way to get information about the server."
    },
    {
      "name": "Subscriptions",
      "description": "Operations related to managing subscriptions, including retrieval, update, approval, rejection, and refreshing the status of connected monetization. For security reasons, API keys, secrets, and other sensitive information included in the subscriptions are not returned in the response."
    },
    {
      "name": "Teams",
      "description": "Teams are a way to group users together. Teams are used to manage team-based access to subscriptions on the platform with internal roles and permissions. Teams typically consist of one to a handful of users."
    },
    {
      "name": "Users",
      "description": "Users are the people who use the platform. Users can be invited to join the platform by an admin or they can sign up themselves. Users can be assigned to teams and have roles and permissions within those teams. Each user has the possibility to be part of one or more teams, each with their separate roles, permissions and subscriptions."
    },
    {
      "name": "Webhooks",
      "description": "# How Webhooks Work\n\nWebhooks are a way for services to communicate with each other in real time. When an event occurs, the Webhook sends an HTTP POST request to the URL that you've configured. The Webhook itself is unaware of any specific authorization mechanisms like the Apiable Lambda authorizer, and the Webhook URL can be any endpoint capable of receiving HTTP POST requests.\n\nOptionally, you can include custom headers in the request. These headers will be appended automatically by the Webhook to the HTTP POST request, adding any additional information required for the endpoint.\n\n ## Testing a Webhook before posting\n\nYou can test a Webhook by sending a POST request to the Webhook URL manually. Here’s an example curl command that simulates the Webhook sending a POST request:\n\n```bash\ncurl -X POST https:/apiable.example.io/webhook \\\n -H \"Content-Type: application/json\" \\\n -H \"api-key: MY-API-KEY\" \\\n -H \"Custom-Header-1: value1\" \\\n -H \"Custom-Header-2: value2\" \\\n -d '{\n   \"id\": \"67040bcb1eb964694d999a68\",\n   \"events\": [\n     \"SUBSCRIPTION_CREATED\"\n   ],\n   \"whsec\": \"whsec_CoX***pc=\"\n }'\n```\n\n## Example Webhook Configuration\n\nIn the following example, a Webhook is configured to send an HTTP POST request to a URL upon the occurrence of a `SUBSCRIPTION_CREATED` event. The parameters \"whsec\" and \"headers\" are optional.\n\n```json\n{\n  \"id\": \"67040bcb1eb964694d999a68\",\n  \"events\": [\n    \"SUBSCRIPTION_CREATED\"\n  ],\n  \"url\": \"https:/apiable.example.io/webhook\",\n  \"headers\": {\n    \"api-key\": \"MY-API-KEY\",\n    \"Custom-Header-1\": \"value1\",\n    \"Custom-Header-2\": \"value2\"\n  }\n}\n```\n       \n    "
    }
  ],
  "paths": {
    "/api/webhooks/{id}": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Retrieve a webhook by ID",
        "description": "Retrieve a specific webhook by its ID. This will return the webhook configuration including the events it is subscribed to, the URL, and the secret key.",
        "operationId": "getWebhookById",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The id of the webhook to retrieve.",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            },
            "example": "67040bcb1eb964694d999a68"
          },
          {
            "name": "X-API-Version",
            "in": "header",
            "description": "API version to use.",
            "required": false,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "2024-09-25"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK: Successfully retrieved the webhook.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The webhook configuration",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "events": {
                      "type": "array",
                      "description": "The events the webhook is listening to",
                      "items": {
                        "type": "string",
                        "description": "The events the webhook is listening to",
                        "enum": [
                          "SUBSCRIPTION_CREATED",
                          "SUBSCRIPTION_CANCELLED",
                          "SUBSCRIPTION_AUTH_CHANGED",
                          "SUBSCRIPTION_CHANGED",
                          "INVOICE_ATTENTION_REQUIRED"
                        ]
                      }
                    },
                    "url": {
                      "type": "string",
                      "description": "The url of the webhook"
                    },
                    "whsec": {
                      "type": "string",
                      "description": "The secret of the webhook"
                    },
                    "authorization": {
                      "type": "string",
                      "description": "The authorization header of the webhook"
                    },
                    "headers": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string",
                        "description": "The headers of the webhook"
                      },
                      "description": "The headers of the webhook"
                    }
                  }
                },
                "examples": {
                  "WebhookConf Example": {
                    "description": "Example of a webhook configuration.",
                    "value": {
                      "id": "66f6b0f0ea99a34963977e55",
                      "created": "2024-09-27T16:19:44.013",
                      "updated": "2024-09-27T16:19:44.013",
                      "name": "Webhook Example",
                      "url": "https://example.com/webhook",
                      "authType": "BASIC_AUTH",
                      "authUsername": "user",
                      "authPassword": "password",
                      "events": [
                        "SUBSCRIPTION_CREATED",
                        "SUBSCRIPTION_CANCELLED"
                      ],
                      "whsec": "whsec_1234567890abcdef",
                      "active": true,
                      "version": 1
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized for operation: getWebhookById",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Unauthorized"
                    },
                    "status": {
                      "type": "string",
                      "example": "401"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found: The requested webhook does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "NotFound": {
                    "description": "Error message when the webhook with the given ID is not found.",
                    "value": "Webhook not found"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "oauth-cc": [
              "apiable/cicd",
              "apiable/platform"
            ]
          }
        ]
      },
      "put": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Update webhook",
        "description": "Update a webhook subscription by providing the URL to send the webhook to, the events to subscribe to.The webhook secret key (whsec) is optional. If not provided, a random key will be generated.\nThe possible event types `SUBSCRIPTION_CREATED` and `SUBSCRIPTION_CANCELLED` are sent when a subscription is created or cancelled, respectively.",
        "operationId": "updateWebhook",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The id of the webhook to be updated.",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            },
            "example": "67040bcb1eb964694d999a68"
          },
          {
            "name": "X-API-Version",
            "in": "header",
            "description": "API version to use.",
            "required": false,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "2024-09-25"
              ]
            }
          }
        ],
        "requestBody": {
          "description": "The expected request body for updating a webhook.",
          "content": {
            "application/json": {
              "schema": {
                "description": "Webhook Configuration update request",
                "properties": {
                  "events": {
                    "type": "array",
                    "description": "The events to subscribe to",
                    "items": {
                      "type": "string",
                      "description": "The events to subscribe to",
                      "enum": [
                        "SUBSCRIPTION_CREATED",
                        "SUBSCRIPTION_CANCELLED",
                        "SUBSCRIPTION_AUTH_CHANGED",
                        "SUBSCRIPTION_CHANGED",
                        "INVOICE_ATTENTION_REQUIRED"
                      ]
                    }
                  },
                  "url": {
                    "type": "string",
                    "description": "The URL to send the webhook to"
                  },
                  "whsec": {
                    "type": "string",
                    "description": "The webhook secret key"
                  },
                  "authorization": {
                    "type": "string",
                    "description": "The authorization header"
                  },
                  "headers": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string",
                      "description": "The headers to send with the webhook"
                    },
                    "description": "The headers to send with the webhook"
                  }
                }
              },
              "examples": {
                "WebhookConfUpdate": {
                  "description": "WebhookConfUpdate",
                  "value": "\n{\n  \"url\": \"https://example.com/webhook\",\n  \"events\": [\n    \"SUBSCRIPTION_CREATED\",\n    \"SUBSCRIPTION_CANCELLED\"\n  ],\n  \"whsec\": \"whsec_1234567890abcdef\",\n}\n"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK: Successfully updated the webhook.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The webhook configuration",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "events": {
                      "type": "array",
                      "description": "The events the webhook is listening to",
                      "items": {
                        "type": "string",
                        "description": "The events the webhook is listening to",
                        "enum": [
                          "SUBSCRIPTION_CREATED",
                          "SUBSCRIPTION_CANCELLED",
                          "SUBSCRIPTION_AUTH_CHANGED",
                          "SUBSCRIPTION_CHANGED",
                          "INVOICE_ATTENTION_REQUIRED"
                        ]
                      }
                    },
                    "url": {
                      "type": "string",
                      "description": "The url of the webhook"
                    },
                    "whsec": {
                      "type": "string",
                      "description": "The secret of the webhook"
                    },
                    "authorization": {
                      "type": "string",
                      "description": "The authorization header of the webhook"
                    },
                    "headers": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string",
                        "description": "The headers of the webhook"
                      },
                      "description": "The headers of the webhook"
                    }
                  }
                },
                "examples": {
                  "WebhookConf Example": {
                    "description": "Example of an updated webhook configuration.",
                    "value": {
                      "id": "66f6b0f0ea99a34963977e55",
                      "created": "2024-09-27T16:19:44.013",
                      "updated": "2024-09-27T16:19:44.013",
                      "name": "Webhook Example",
                      "url": "https://example.com/webhook",
                      "authType": "BASIC_AUTH",
                      "authUsername": "user",
                      "authPassword": "password",
                      "events": [
                        "SUBSCRIPTION_CREATED",
                        "SUBSCRIPTION_CANCELLED"
                      ],
                      "whsec": "whsec_1234567890abcdef",
                      "active": true,
                      "version": 1
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized for operation: updateWebhook",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Unauthorized"
                    },
                    "status": {
                      "type": "string",
                      "example": "401"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found: The webhook to be updated does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "NotFound": {
                    "description": "Error message when the webhook with the given ID is not found.",
                    "value": "Webhook not found"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "oauth-cc": [
              "apiable/cicd",
              "apiable/platform"
            ]
          }
        ]
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Unregister a webhook",
        "description": "Unsubscribe from a webhook, record of the webhook will be deleted and deleted webhook will no longer receive events. Restoring a deleted webhook is not possible, instead you can create a new webhook with the same configuration.",
        "operationId": "unregisterWebhook",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The id of the webhook to be unregistered.",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            },
            "example": "67040bcb1eb964694d999a68"
          },
          {
            "name": "X-API-Version",
            "in": "header",
            "description": "API version to use.",
            "required": false,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "2024-09-25"
              ]
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No Content: Successfully unregistered the webhook.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "Success": {
                    "description": "Confirmation message when the webhook is successfully unregistered.",
                    "value": "Webhook unregistered successfully"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized for operation: unregisterWebhook",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Unauthorized"
                    },
                    "status": {
                      "type": "string",
                      "example": "401"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found: The webhook to be unregistered doesn't exit.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "NotFound": {
                    "description": "Error message when the webhook with the given ID is not found.",
                    "value": "Webhook not found"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "oauth-cc": [
              "apiable/cicd",
              "apiable/platform"
            ]
          }
        ]
      }
    },
    "/api/users/{id}/roles": {
      "put": {
        "tags": [
          "Users"
        ],
        "summary": "Update User Roles",
        "description": "Update the roles of a user. The roles are used to define the permissions of the user within the platform. The roles are defined by the platform admin and can be assigned to users by the platform admin or team admins.",
        "operationId": "updateUserRoles",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The id of the user to be updated the team roles.",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            },
            "example": "6409edb91c6c14300fce1a3c"
          },
          {
            "name": "X-API-Version",
            "in": "header",
            "description": "API version to use.",
            "required": false,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "2024-09-25"
              ]
            }
          }
        ],
        "requestBody": {
          "description": "List of roles that need to be assigned to the user.",
          "content": {
            "application/json": {
              "schema": {
                "description": "The role and permissions that a user has in a team",
                "properties": {
                  "teamId": {
                    "type": "string"
                  },
                  "accessDetails": {
                    "description": "Access details and role that the invited user will have",
                    "properties": {
                      "roleName": {
                        "type": "string",
                        "enum": [
                          "ADMIN",
                          "READ_ONLY",
                          "RESTRICTED"
                        ]
                      },
                      "apiKeys": {
                        "type": "string",
                        "enum": [
                          "NONE",
                          "READ",
                          "FULL"
                        ]
                      },
                      "billing": {
                        "type": "string",
                        "enum": [
                          "NONE",
                          "READ",
                          "FULL"
                        ]
                      },
                      "teams": {
                        "type": "string",
                        "enum": [
                          "NONE",
                          "READ",
                          "FULL"
                        ]
                      }
                    }
                  }
                }
              },
              "examples": {
                "Example roles": {
                  "description": "User roles.",
                  "value": "\n[\n  {\n    \"teamId\": \"66fbb93c4220cc7d307a5b0a\",\n    \"accessDetails\": {\n      \"roleName\": \"CUSTOM\"\n      \"apiKeys\": \"FULL\",\n      \"billing\": \"READ\",\n      \"teams\": \"NONE\"\n    }\n  }\n]\n"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The user object with the updated fields. The change of the roles will be reflected by the field 'roles' in user.metadata object.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "User object",
                  "properties": {
                    "version": {
                      "type": "integer",
                      "format": "int32"
                    },
                    "created": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updated": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "id": {
                      "type": "string"
                    },
                    "providerId": {
                      "type": "string",
                      "description": "The provider id of the user"
                    },
                    "metadata": {
                      "description": "The metadata of the user",
                      "properties": {
                        "activeTeam": {
                          "description": "Unique identifier to an object",
                          "properties": {
                            "id": {
                              "type": "string"
                            }
                          }
                        },
                        "agreesToReceiveEmail": {
                          "type": "boolean",
                          "description": "Flag to indicate if the user has given consent to receive emails"
                        },
                        "postRegistrationWizardComplete": {
                          "type": "boolean",
                          "description": "Flag to indicate if the user has completed the registration wizard"
                        },
                        "approval": {
                          "type": "string",
                          "description": "Flag to indicate if the user has been approved, if approval process is in place",
                          "enum": [
                            "PENDING",
                            "ACTIVE",
                            "REJECTED"
                          ]
                        },
                        "teams": {
                          "type": "array",
                          "description": "List of teams that the user is part of",
                          "items": {
                            "description": "Unique identifier to an object",
                            "properties": {
                              "id": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "stripeCustomerId": {
                          "type": "string",
                          "description": "The monetization integration ID of

# --- truncated at 32 KB (890 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apiable/refs/heads/main/openapi/apiable-platform-api-openapi.json