{"components":{"parameters":{"IntegrationId":{"in":"path","name":"id","required":true,"schema":{"maxLength":128,"type":"string"}},"IntegrationTypeName":{"in":"path","name":"type","required":true,"schema":{"$ref":"#/components/schemas/IntegrationTypeName"}},"PageSize":{"description":"Items per page, at most 100. Default 50.","in":"query","name":"pageSize","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},"PageToken":{"description":"The `nextPageToken` of the previous page.","in":"query","name":"pageToken","schema":{"maxLength":1024,"type":"string"}}},"responses":{"Problem":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"An error."}},"schemas":{"AwsSetup":{"description":"The IAM role Catio assumes in your account.","properties":{"policyArns":{"description":"Managed policies to attach to the role.","items":{"type":"string"},"type":"array"},"roleName":{"example":"CatioConsoleAccessRole","type":"string"},"trustedPrincipalArn":{"description":"The principal to trust in the role's trust policy, with your external id as `sts:ExternalId`.","example":"arn:aws:iam::090135924592:role/CatioPlatformAccessIRSA","type":"string"}},"required":["roleName","trustedPrincipalArn"],"type":"object"},"CreateIntegrationRequest":{"additionalProperties":false,"properties":{"name":{"maxLength":200,"minLength":1,"type":"string"},"properties":{"additionalProperties":{"maxLength":4096,"type":"string"},"description":"Values for the type's properties, by property name.","type":"object"},"schedule":{"allOf":[{"$ref":"#/components/schemas/ScheduleUpdate"}],"description":"Defaults to enabled, every 48 hours."},"type":{"$ref":"#/components/schemas/IntegrationTypeName"}},"required":["type","name","properties"],"type":"object"},"Integration":{"properties":{"createdAt":{"format":"date-time","type":"string"},"createdBy":{"description":"`user:\u003cid\u003e` or `apikey:\u003ckey id\u003e`.","type":"string"},"id":{"type":"string"},"lastRun":{"$ref":"#/components/schemas/Run"},"name":{"type":"string"},"nextRunAt":{"format":"date-time","type":"string"},"properties":{"additionalProperties":true,"description":"The property values. Secret properties are never returned.","type":"object"},"schedule":{"$ref":"#/components/schemas/Schedule"},"type":{"$ref":"#/components/schemas/IntegrationTypeName"},"updatedAt":{"format":"date-time","type":"string"},"updatedBy":{"type":"string"}},"required":["id","type","name","properties","schedule","createdAt","updatedAt"],"type":"object"},"IntegrationList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Integration"},"type":"array"},"nextPageToken":{"type":"string"}},"required":["data"],"type":"object"},"IntegrationType":{"properties":{"description":{"type":"string"},"identifiedBy":{"description":"The properties whose values identify an integration of this type.\nThe organization can have one integration per set of values.\n","items":{"type":"string"},"type":"array"},"name":{"example":"AWS","type":"string"},"properties":{"items":{"$ref":"#/components/schemas/PropertyDefinition"},"type":"array"},"setup":{"$ref":"#/components/schemas/AwsSetup"},"type":{"$ref":"#/components/schemas/IntegrationTypeName"}},"required":["type","name","description","properties","identifiedBy"],"type":"object"},"IntegrationTypeList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/IntegrationType"},"type":"array"}},"required":["data"],"type":"object"},"IntegrationTypeName":{"description":"`aws`: an AWS account's resources. `aws-vpc-flow-logs`: VPC flow\nlogs. `aws-cost-usage`: an AWS Cost and Usage Report.\n","enum":["aws","aws-vpc-flow-logs","aws-cost-usage"],"type":"string"},"Problem":{"description":"An RFC 9457 problem.","properties":{"code":{"description":"Stable and safe to branch on: `invalid_request`,\n`invalid_property`, `unauthenticated`, `forbidden`, `not_found`,\n`integration_exists`, `rate_limited`, `unavailable`, `internal`.\n","example":"not_found","type":"string"},"detail":{"type":"string"},"existingId":{"description":"For `integration_exists`, the existing integration.","type":"string"},"permission":{"description":"For `forbidden`, the permission the key lacks.","type":"string"},"property":{"description":"For `invalid_property`, the property at fault.","type":"string"},"requestId":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"example":"about:blank","type":"string"}},"required":["type","title","status","code"],"type":"object"},"PropertyDefinition":{"properties":{"description":{"type":"string"},"displayName":{"type":"string"},"name":{"example":"AWS_ACCOUNT_ID","type":"string"},"options":{"description":"The allowed values, when there is a fixed set.","items":{"type":"string"},"type":"array"},"pattern":{"description":"A regular expression the value must match.","type":"string"},"required":{"type":"boolean"},"secret":{"description":"The value is stored encrypted and never returned.","type":"boolean"},"type":{"description":"What the value represents. Values are always sent as JSON strings,\nso send an integer as `\"5\"` and a boolean as `\"true\"`.\n","enum":["string","integer","boolean"],"type":"string"}},"required":["name","type","required","secret"],"type":"object"},"Run":{"properties":{"id":{"type":"string"},"messages":{"description":"The run's errors and warnings, oldest first.","items":{"$ref":"#/components/schemas/RunMessage"},"type":"array"},"stages":{"items":{"$ref":"#/components/schemas/RunStage"},"type":"array"},"startedAt":{"format":"date-time","type":"string"},"status":{"$ref":"#/components/schemas/RunStatus"}},"required":["id","status","stages","messages"],"type":"object"},"RunList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Run"},"type":"array"},"nextPageToken":{"type":"string"}},"required":["data"],"type":"object"},"RunMessage":{"properties":{"level":{"enum":["error","warning"],"type":"string"},"stage":{"type":"string"},"text":{"type":"string"},"time":{"format":"date-time","type":"string"}},"required":["level","text"],"type":"object"},"RunStage":{"properties":{"completedAt":{"format":"date-time","type":"string"},"name":{"type":"string"},"startedAt":{"format":"date-time","type":"string"},"status":{"$ref":"#/components/schemas/RunStatus"}},"required":["name","status"],"type":"object"},"RunStatus":{"enum":["running","succeeded","failed","cancelled"],"type":"string"},"Schedule":{"properties":{"enabled":{"type":"boolean"},"intervalHours":{"maximum":8760,"minimum":1,"type":"integer"}},"required":["enabled","intervalHours"],"type":"object"},"ScheduleUpdate":{"additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"intervalHours":{"maximum":8760,"minimum":1,"type":"integer"}},"type":"object"},"StartedRun":{"properties":{"created":{"description":"True when this call started the run.","type":"boolean"},"runId":{"description":"The run's id, for `GET /v1/integrations/{id}/runs/{runId}`. Absent\nfor `aws-cost-usage`, whose run id is not known when it starts;\nfind the run with `GET /v1/integrations/{id}/runs`.\n","type":"string"}},"required":["created"],"type":"object"},"UpdateIntegrationRequest":{"additionalProperties":false,"properties":{"name":{"maxLength":200,"minLength":1,"type":"string"},"properties":{"additionalProperties":{"maxLength":4096,"type":"string"},"description":"Only the properties that change.","type":"object"},"schedule":{"$ref":"#/components/schemas/ScheduleUpdate"},"type":{"allOf":[{"$ref":"#/components/schemas/IntegrationTypeName"}],"description":"Cannot change. Sending a different type is a 400."}},"type":"object"}},"securitySchemes":{"apiKey":{"description":"A Catio API key, `catio_` followed by 49 characters.","scheme":"bearer","type":"http"}}},"info":{"description":"Manage your Catio integrations from scripts, CI pipelines and\ninfrastructure as code.\n\n**Authentication.** Send a Catio API key as a bearer token:\n`Authorization: Bearer catio_...`. Admins create keys in the Catio\nconsole under Settings → API keys. A key belongs to one organization and\nholds a set of permissions; every operation names the permission it needs.\n\n**Errors** are `application/problem+json` (RFC 9457) with a stable `code`.\n\n**Rate limit.** 300 requests per minute per API key. Over the limit the\nAPI answers 429 with a `Retry-After` header.\n\n**Versioning.** Paths start with `/v1`. Within a version, changes are\nadditive only: new fields and new operations, never removed or renamed\nones.\n","title":"Catio API","version":"1.0.0"},"openapi":"3.0.3","paths":{"/v1/integration-types":{"get":{"description":"The integration types the API can create.","operationId":"ListIntegrationTypes","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationTypeList"}}},"description":"The integration types."},"default":{"$ref":"#/components/responses/Problem"}},"summary":"List integration types","tags":["Integration types"],"x-catio-operation":"integrationTypes.read"}},"/v1/integration-types/{type}":{"get":{"operationId":"GetIntegrationType","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationType"}}},"description":"The integration type."},"default":{"$ref":"#/components/responses/Problem"}},"summary":"Get an integration type","tags":["Integration types"],"x-catio-operation":"integrationTypes.read"},"parameters":[{"$ref":"#/components/parameters/IntegrationTypeName"}]},"/v1/integrations":{"get":{"description":"The organization's integrations, one page at a time. A page can hold\nfewer than `pageSize` items, even none, when a `type` filter is set;\nkeep reading while `nextPageToken` is present.\n","operationId":"ListIntegrations","parameters":[{"description":"Only integrations of this type.","in":"query","name":"type","schema":{"$ref":"#/components/schemas/IntegrationTypeName"}},{"$ref":"#/components/parameters/PageSize"},{"$ref":"#/components/parameters/PageToken"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationList"}}},"description":"A page of integrations."},"default":{"$ref":"#/components/responses/Problem"}},"summary":"List integrations","tags":["Integrations"],"x-catio-operation":"integrations.read"},"post":{"description":"Creates an integration and starts its schedule.\n\nSafe to retry: when an integration of the same type already exists for\nthe same identifying properties (for `aws`, the account id) and every\nproperty is the same, the API answers 200 with that integration\ninstead of creating a second one. When the identifying properties match\nbut other properties differ, it answers 409 `integration_exists` with\nthe existing integration's id.\n\nFor `aws` types, create a random external id of at least 16\ncharacters, create the IAM role described by\n`GET /v1/integration-types/{type}` (`setup`), then send the external id\nas `AWS_EXTERNAL_ID`.\n","operationId":"CreateIntegration","requestBody":{"content":{"application/json":{"example":{"name":"prod-123456789012","properties":{"AWS_ACCOUNT_ID":"123456789012","AWS_EXTERNAL_ID":"\u003crandom, at least 16 characters\u003e","AWS_REGIONS_LIST":"*"},"schedule":{"enabled":true,"intervalHours":24},"type":"aws"},"schema":{"$ref":"#/components/schemas/CreateIntegrationRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Integration"}}},"description":"The same integration already existed (a retry)."},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Integration"}}},"description":"The integration was created."},"default":{"$ref":"#/components/responses/Problem"}},"summary":"Create an integration","tags":["Integrations"],"x-catio-operation":"integrations.create"}},"/v1/integrations/{id}":{"delete":{"description":"Stops its schedule and removes it. Its data stays in Catio.","operationId":"DeleteIntegration","responses":{"204":{"description":"The integration was deleted."},"default":{"$ref":"#/components/responses/Problem"}},"summary":"Delete an integration","tags":["Integrations"],"x-catio-operation":"integrations.delete"},"get":{"operationId":"GetIntegration","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Integration"}}},"description":"The integration."},"default":{"$ref":"#/components/responses/Problem"}},"summary":"Get an integration","tags":["Integrations"],"x-catio-operation":"integrations.read"},"parameters":[{"$ref":"#/components/parameters/IntegrationId"}],"patch":{"description":"A JSON merge patch (RFC 7396) of `name`, `properties` and `schedule`.\nSend only what changes: a property you leave out keeps its value, so a\nsecret can be rotated on its own. The type cannot change.\n","operationId":"UpdateIntegration","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateIntegrationRequest"}},"application/merge-patch+json":{"schema":{"$ref":"#/components/schemas/UpdateIntegrationRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Integration"}}},"description":"The updated integration."},"default":{"$ref":"#/components/responses/Problem"}},"summary":"Update an integration","tags":["Integrations"],"x-catio-operation":"integrations.update"}},"/v1/integrations/{id}/runs":{"get":{"description":"The integration's runs, newest first.","operationId":"ListRuns","parameters":[{"$ref":"#/components/parameters/PageSize"},{"$ref":"#/components/parameters/PageToken"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunList"}}},"description":"A page of runs."},"default":{"$ref":"#/components/responses/Problem"}},"summary":"List runs","tags":["Runs"],"x-catio-operation":"integrationRuns.read"},"parameters":[{"$ref":"#/components/parameters/IntegrationId"}],"post":{"description":"Starts an extraction run now and returns at once; it does not wait for\nthe run. Safe to retry: while a run is active, the API answers 200\nwith that run instead of starting another.\n","operationId":"StartRun","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartedRun"}}},"description":"A run was already active; nothing was started."},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartedRun"}}},"description":"A run was started."},"default":{"$ref":"#/components/responses/Problem"}},"summary":"Start a run","tags":["Runs"],"x-catio-operation":"integrations.trigger"}},"/v1/integrations/{id}/runs/{runId}":{"get":{"operationId":"GetRun","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}},"description":"The run."},"default":{"$ref":"#/components/responses/Problem"}},"summary":"Get a run","tags":["Runs"],"x-catio-operation":"integrationRuns.read"},"parameters":[{"$ref":"#/components/parameters/IntegrationId"},{"in":"path","name":"runId","required":true,"schema":{"maxLength":128,"type":"string"}}]}},"security":[{"apiKey":[]}],"servers":[{"description":"Production","url":"https://api.catio.tech"},{"description":"Development","url":"https://api.dev.catio.tech"}],"tags":[{"description":"The kinds of integration you can create, and their properties.","name":"Integration types"},{"description":"Your organization's integrations.","name":"Integrations"},{"description":"Extraction runs of an integration.","name":"Runs"}]}