{ "swagger": "2.0", "info": { "title": "Afi API Calls", "description": "Afi API Description", "version": "1.0", "contact": { "name": "Afi", "url": "https://afi.ai/docs/", "email": "support@afi.ai" } }, "tags": [ { "name": "Applications" }, { "name": "Archives" }, { "name": "Audit" }, { "name": "Licensing" }, { "name": "Orgs" }, { "name": "Policies" }, { "name": "Protections" }, { "name": "Resources" }, { "name": "Tasks" }, { "name": "Tenants" } ], "host": "papi.afi.ai", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/api/v1/applications/me/installations": { "get": { "summary": "List application installations", "description": "Lists installations for the application identified by the authentication key.\nUse the `limit` and `page_token` query parameters to paginate through all installations.", "operationId": "Applications_ListInstallations", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1InstallationPage" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "limit", "description": "Maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int32" }, { "name": "page_token", "description": "Token from the previous list operation (`next_page_token`) used to continue listing.", "in": "query", "required": false, "type": "string" } ], "tags": [ "Applications" ] } }, "/api/v1/orgs": { "post": { "summary": "Create an organization", "description": "Creates a new child organization.", "operationId": "Orgs_CreateOrg", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1CreateOrgResult" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "parent_org_id", "description": "ID of the existing parent organization.", "in": "query", "required": false, "type": "string" }, { "name": "external_id", "description": "External ID for the new organization.\nUse it for idempotency to prevent duplicate organizations and to map the organization\nto the matching one in an external system that integrates with Afi.", "in": "query", "required": false, "type": "string" }, { "name": "name", "description": "Name of the new organization.", "in": "query", "required": false, "type": "string" }, { "name": "admin_email", "description": "Email address of the administrator account.\nAn email with an invitation link is sent to this address.", "in": "query", "required": false, "type": "string" } ], "tags": [ "Orgs" ] } }, "/api/v1/orgs/{id}": { "get": { "summary": "Retrieve an organization", "description": "Retrieves an organization by its ID.", "operationId": "Orgs_GetOrg", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1Org" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "id", "description": "ID of the organization to retrieve.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Orgs" ] } }, "/api/v1/orgs/{org_id}/licensing/subscriptions": { "get": { "summary": "List organization subscriptions", "description": "Returns subscription details for the specified organization.\nEach tenant in the organization has its own subscription.\nUse the `limit` and `page_token` query parameters to paginate the results.", "operationId": "Licensing_ListSubscriptions", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1SubscriptionsPage" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "org_id", "description": "ID of the organization whose subscriptions to list.", "in": "path", "required": true, "type": "string" }, { "name": "limit", "description": "Maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int32" }, { "name": "page_token", "description": "Token from the previous list operation (`next_page_token`) used to continue listing.", "in": "query", "required": false, "type": "string" } ], "tags": [ "Licensing" ] } }, "/api/v1/orgs/{org_id}/licensing/subscriptions/history": { "get": { "summary": "Retrieve subscription history", "description": "Returns historical usage for the organization's subscriptions\nover the requested period. If the licensed quantity changes during\nthat period, the response includes multiple records for the same subscription.\n\nOnly post-pay subscriptions are included in the response.", "operationId": "Licensing_GetSubscriptionHistory", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1SubscriptionHistoryResult" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "org_id", "description": "ID of the organization whose subscription history to retrieve.", "in": "path", "required": true, "type": "string" }, { "name": "start", "description": "Start of the reporting window. Use RFC 3339 format.\nThe window must span 1 to 40 days.", "in": "query", "required": false, "type": "string", "format": "date-time" }, { "name": "end", "description": "End of the reporting window. Use RFC 3339 format.\nMust be at least one hour before the current time.", "in": "query", "required": false, "type": "string", "format": "date-time" } ], "tags": [ "Licensing" ] } }, "/api/v1/orgs/{org_id}/orgs": { "get": { "summary": "List child organizations", "description": "Lists child organizations of the specified parent organization.\nThe root organization and its sub-organizations form a hierarchy.\nEach organization in the hierarchy can own tenants and resources.\n\nUse the `limit` and `page_token` query parameters to paginate through the hierarchy.", "operationId": "Orgs_ListOrgOrgs", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1OrgsPage" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "org_id", "description": "ID of the parent organization whose child organizations to list.", "in": "path", "required": true, "type": "string" }, { "name": "limit", "description": "Maximum number of items to return per page (default 100).", "in": "query", "required": false, "type": "integer", "format": "int32" }, { "name": "page_token", "description": "Token from the previous list operation (`next_page_token`) used to continue listing.", "in": "query", "required": false, "type": "string" } ], "tags": [ "Orgs" ] } }, "/api/v1/orgs/{org_id}/tenants": { "get": { "summary": "List an organization's tenants", "description": "Lists tenants for the specified organization ID.\nUse the `limit` and `page_token` query parameters to paginate through tenants.", "operationId": "Tenants_GetOrgTenants", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1TenantsPage" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "org_id", "description": "ID of the organization whose tenants to list.", "in": "path", "required": true, "type": "string" }, { "name": "limit", "description": "Maximum number of items to return per page (default 100).", "in": "query", "required": false, "type": "integer", "format": "int32" }, { "name": "page_token", "description": "Token from the previous list operation (`next_page_token`) used to continue listing.", "in": "query", "required": false, "type": "string" } ], "tags": [ "Tenants" ] } }, "/api/v1/tenants/{id}": { "get": { "summary": "Retrieve a tenant", "description": "Retrieves a tenant by its ID.", "operationId": "Tenants_GetTenant", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1Tenant" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "id", "description": "ID of the tenant to retrieve.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Tenants" ] } }, "/api/v1/tenants/{id}/quotas": { "get": { "summary": "Get tenant usage and quotas", "description": "Retrieves usage and quota limits for the tenant.", "operationId": "Tenants_GetTenantQuotas", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1TenantQuotas" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "id", "description": "ID of the tenant to retrieve quotas for.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Tenants" ] } }, "/api/v1/tenants/{tenant_id}/archives": { "get": { "summary": "List archives", "description": "Retrieves the archives for the specified tenant and, optionally, for the specified resource in this tenant.", "operationId": "Archives_ListArchives", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1ArchivePage" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "tenant_id", "description": "ID of the tenant whose archives to list.", "in": "path", "required": true, "type": "string" }, { "name": "resource_id", "description": "Optional resource ID used to filter the results.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "Maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int32" }, { "name": "page_token", "description": "Token from the previous list operation (`next_page_token`) used to continue listing.", "in": "query", "required": false, "type": "string" } ], "tags": [ "Archives" ] } }, "/api/v1/tenants/{tenant_id}/archives/{id}": { "delete": { "summary": "Delete an archive", "description": "Schedules the archive for deletion. The default delay is 7 days, during which the deletion can be canceled.", "operationId": "Archives_DeleteArchive", "responses": { "200": { "description": "A successful response.", "schema": { "type": "object", "properties": {} } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "tenant_id", "description": "Tenant ID that owns the archive.", "in": "path", "required": true, "type": "string" }, { "name": "id", "description": "ID of the archive to delete.", "in": "path", "required": true, "type": "string" }, { "name": "reason", "description": "Reason for requesting archive deletion. Provide a mandatory description up to 128 bytes long.", "in": "query", "required": true, "type": "string" } ], "tags": [ "Archives" ] } }, "/api/v1/tenants/{tenant_id}/audit/events": { "get": { "summary": "List tenant audit events", "description": "Retrieves audit events for the specified tenant.\nUse the `limit` and `page_token` query parameters to paginate through all events.", "operationId": "Audit_ListAuditEvents", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1AuditEventsPage" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "tenant_id", "description": "ID of the tenant whose events to list.", "in": "path", "required": true, "type": "string" }, { "name": "limit", "description": "Maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int32" }, { "name": "page_token", "description": "Token from the previous list operation (`next_page_token`) used to continue listing.", "in": "query", "required": false, "type": "string" }, { "name": "start_time", "description": "Start of the time range for retrieving audit events.\nUse RFC 3339 format.", "in": "query", "required": false, "type": "string", "format": "date-time" }, { "name": "end_time", "description": "End of the time range for retrieving audit events.\nUse RFC 3339 format.", "in": "query", "required": false, "type": "string", "format": "date-time" } ], "tags": [ "Audit" ] } }, "/api/v1/tenants/{tenant_id}/jobs/{job_id}/trigger": { "put": { "summary": "Trigger an out-of-schedule job", "description": "Triggers an out-of-schedule job execution, spawns a task, and returns its ID.", "operationId": "Tasks_TriggerJob", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1TriggerJobResult" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "tenant_id", "description": "Tenant ID that owns the job.", "in": "path", "required": true, "type": "string" }, { "name": "job_id", "description": "ID of the job to trigger.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Tasks" ] } }, "/api/v1/tenants/{tenant_id}/policies": { "get": { "summary": "List policies", "description": "Retrieves policies available to the tenant.\nUse the `limit` and `page_token` query parameters to paginate through all policies.", "operationId": "Policies_ListPolicies", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1PoliciesPage" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "tenant_id", "description": "ID of the tenant whose policies to list.", "in": "path", "required": true, "type": "string" }, { "name": "limit", "description": "Maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int32" }, { "name": "page_token", "description": "Token from the previous list operation (`next_page_token`) used to continue listing.", "in": "query", "required": false, "type": "string" }, { "name": "name", "description": "Optional filter by policy name.", "in": "query", "required": false, "type": "string" } ], "tags": [ "Policies" ] } }, "/api/v1/tenants/{tenant_id}/protections": { "get": { "summary": "List protections", "description": "Retrieves protections assigned to resources in the tenant.\nUse the `limit` and `page_token` query parameters to paginate through all protections.", "operationId": "Protections_ListProtections", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1ProtectionPage" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "tenant_id", "description": "Tenant for which to list protections.", "in": "path", "required": true, "type": "string" }, { "name": "resource_id", "description": "ID of the resource whose protections to list.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "Maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int32" }, { "name": "page_token", "description": "Token from the previous list operation (`next_page_token`) used to continue listing.", "in": "query", "required": false, "type": "string" } ], "tags": [ "Protections" ] } }, "/api/v1/tenants/{tenant_id}/resources": { "get": { "summary": "List resources", "description": "Retrieves resources owned by the tenant.\nUse the `limit` and `page_token` query parameters to paginate through all resources.", "operationId": "Resources_ListResources", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1ResourcePage" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "tenant_id", "description": "ID of the tenant whose resources to list.", "in": "path", "required": true, "type": "string" }, { "name": "limit", "description": "Maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int32" }, { "name": "page_token", "description": "Token from the previous list operation (`next_page_token`) used to continue listing.", "in": "query", "required": false, "type": "string" } ], "tags": [ "Resources" ] } }, "/api/v1/tenants/{tenant_id}/resources/statistics/summary": { "get": { "summary": "Get resource protection statistics", "description": "Retrieves protection statistics for resources in the tenant, grouped by resource kind.", "operationId": "Resources_GetResourcesStats", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1ResourceStats" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "tenant_id", "description": "ID of the tenant for which to retrieve resource statistics.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Resources" ] } }, "/api/v1/tenants/{tenant_id}/resources/{id}": { "get": { "summary": "Retrieve a resource", "description": "Retrieves a resource by its ID or external ID.", "operationId": "Resources_GetResource", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1Resource" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "tenant_id", "description": "Tenant that owns the resource.", "in": "path", "required": true, "type": "string" }, { "name": "id", "description": "ID of the resource to retrieve. An external ID can be used if prefixed with `ext$`.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Resources" ] } }, "/api/v1/tenants/{tenant_id}/resources/{resource_id}/protect": { "delete": { "summary": "Unprotect a resource", "description": "Unassigns the specified policy from the resource.", "operationId": "Protections_UnprotectResource", "responses": { "200": { "description": "A successful response.", "schema": { "type": "object", "properties": {} } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "tenant_id", "description": "Tenant that owns the resource.", "in": "path", "required": true, "type": "string" }, { "name": "resource_id", "description": "ID of the resource to unprotect. External IDs are not supported here.", "in": "path", "required": true, "type": "string" }, { "name": "policy_id", "description": "Policy ID to remove from the resource.", "in": "query", "required": true, "type": "string" } ], "tags": [ "Protections" ] }, "post": { "summary": "Protect a resource", "description": "Assigns the specified policy to the resource. By default, a resource can have at most one policy.", "operationId": "Protections_ProtectResource", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1ProtectResourceResult" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "tenant_id", "description": "Tenant that owns the resource.", "in": "path", "required": true, "type": "string" }, { "name": "resource_id", "description": "ID of the resource to protect. External IDs are not supported here.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "properties": {} } }, { "name": "policy_id", "description": "Policy ID to assign to the resource.", "in": "query", "required": true, "type": "string" } ], "tags": [ "Protections" ] } }, "/api/v1/tenants/{tenant_id}/tasks/statistics/summary": { "get": { "summary": "Get task status statistics for a tenant", "description": "Returns task statistics aggregated by task status for a given time period.\nThe period must be no longer than 31 days and must fall within the most recent 35 days.\nThe `tenant_id` path parameter specifies which tenant's statistics to retrieve.", "operationId": "Tasks_GetTaskTenantStats", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1TaskTenantStats" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "tenant_id", "description": "ID of the tenant whose task statistics to retrieve.", "in": "path", "required": true, "type": "string" }, { "name": "start_time", "description": "Start of the period for retrieving tenant task statistics.\nSpecify the timestamp with hour granularity to align day-level statistics with a specific time zone.\nValues are rounded to the nearest hour if not already rounded by the caller.\nUse the RFC 3339 timestamp format.", "in": "query", "required": true, "type": "string", "format": "date-time" }, { "name": "end_time", "description": "End of the period for retrieving the statistics.", "in": "query", "required": true, "type": "string", "format": "date-time" } ], "tags": [ "Tasks" ] } }, "/api/v1/tenants/{tenant_id}/tasks/{task_id}": { "get": { "summary": "Retrieve a task", "description": "Retrieves a task object by its ID.\n\nPoll the task status using exponentially increasing intervals while waiting for completion:\nStart at 15 seconds and double the interval up to 4 minutes (15 s, 30 s, 60 s, 2 min, 4 min).\nPolling more frequently is unnecessary; the cached state will not change sooner and doing so increases\nthe likelihood of HTTP 429 errors because of rate limits.", "operationId": "Tasks_GetTask", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1Task" } }, "400": { "description": "Invalid argument. The request is missing required arguments or contains invalid values.", "schema": {} }, "401": { "description": "Unauthenticated. The API key is invalid, expired, or missing.", "schema": {} }, "403": { "description": "Forbidden. The application does not have permission to access the entity.", "schema": {} }, "404": { "description": "Not found. The requested entity does not exist.", "schema": {} }, "429": { "description": "Too many requests. The application exceeded its API call limit and should reduce the request rate. Use exponential backoff to handle rate limiting.", "schema": {} } }, "parameters": [ { "name": "tenant_id", "description": "Tenant ID that owns the task.", "in": "path", "required": true, "type": "string" }, { "name": "task_id", "description": "ID of the task to retrieve.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Tasks" ] } } }, "definitions": { "v1Archive": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the archive." }, "tenant_id": { "type": "string", "description": "ID of the tenant that owns the archive." }, "resource_id": { "type": "string", "description": "ID of the resource associated with the archive." }, "delete_pending": { "type": "boolean", "description": "Indicates whether the archive and its data are scheduled for deletion." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the archive was created." }, "stats": { "$ref": "#/definitions/v1ArchiveStats", "description": "Statistics related to the archive." } }, "description": "Archive represents a set of related backups (a backup sequence) of a single resource stored in the same location,\nsuch as a full backup followed by incremental backups.\nA resource can have several backup archives associated with it." }, "v1ArchivePage": { "type": "object", "properties": { "next_page_token": { "type": "string", "description": "Token for the next page in the listing operation. Set this value as `page_token` in the subsequent request. Empty on the last page." }, "items": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1Archive" }, "description": "List of archives." } }, "description": "ArchivePage contains the results of listing archives." }, "v1ArchiveStats": { "type": "object", "properties": { "size": { "type": "string", "format": "uint64", "description": "Storage size used by the archive, in KB." } }, "description": "ArchiveStats provides storage and other statistics for the archive." }, "v1AuditEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event ID." }, "actor_email": { "type": "string", "description": "Email address of the actor who triggered the event." }, "actor_name": { "type": "string", "description": "Name of the actor who triggered the event." }, "action": { "type": "string", "description": "Action performed by the actor." }, "subject": { "type": "string", "description": "Subject affected by the action." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event was created." }, "details": { "type": "string", "description": "Additional event information in JSON format.\nThe exact structure depends on the audit event type and may change in future product versions." } }, "description": "AuditEvent describes an audit event." }, "v1AuditEventsPage": { "type": "object", "properties": { "next_page_token": { "type": "string", "description": "Token for the next page in the listing operation. Set this value as `page_token` in the subsequent request. Empty on the last page." }, "items": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1AuditEvent" }, "description": "List of audit events." } }, "description": "AuditEventsPage contains the results of listing audit events." }, "v1CreateOrgResult": { "type": "object", "properties": { "org": { "$ref": "#/definitions/v1Org", "description": "The newly created organization." }, "invitation_url": { "type": "string", "description": "An invitation URL that the user can follow to log in, accepting the invitation, and become the organization's administrator." } }, "description": "CreateOrgResult is the result of an organization creation request." }, "v1Installation": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "Tenant where the application is installed.\nEmpty for organization-wide installations." }, "org_id": { "type": "string", "description": "Organization where the application is installed.\nEmpty for tenant-level installations." } }, "description": "Installation describes the properties of an application installation.\n\nApplications can be installed for specific tenants or across an entire organization.\nIn organization-wide installations, `tenant_id` is empty.\nUse the child organization listing API to enumerate tenants in the organization associated with the installation." }, "v1InstallationPage": { "type": "object", "properties": { "next_page_token": { "type": "string", "description": "Token for the next page in the listing operation. Set this value as `page_token` in the subsequent request. Empty on the last page." }, "items": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1Installation" }, "description": "List of installations." } }, "description": "InstallationPage contains the results of listing application installations." }, "v1Org": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the organization." }, "external_id": { "type": "string", "description": "Unique external ID of the organization." }, "kind": { "type": "string", "description": "Organization kind (distributor, msp, basic)." }, "name": { "type": "string", "description": "Organization name." } }, "description": "Org represents an organization." }, "v1OrgsPage": { "type": "object", "properties": { "next_page_token": { "type": "string", "description": "Token for the next page in the listing operation. Set this value as `page_token` in the subsequent request. Empty on the last page." }, "items": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1Org" }, "description": "List of organizations." } }, "description": "OrgsPage contains the results of listing organizations." }, "v1PoliciesPage": { "type": "object", "properties": { "next_page_token": { "type": "string", "description": "Token for the next page in the listing operation. Set this value as `page_token` in the subsequent request. Empty on the last page." }, "items": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1Policy" }, "description": "List of policies." } }, "description": "PoliciesPage contains the results of listing policies." }, "v1Policy": { "type": "object", "properties": { "id": { "type": "string", "description": "Policy ID." }, "tenant_id": { "type": "string", "description": "Tenant that owns the policy." }, "name": { "type": "string", "description": "Policy name." } }, "description": "Policy describes a tenant policy." }, "v1ProtectResourceResult": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Job ID corresponding to the protection." } }, "description": "ProtectResourceResult contains the job associated with a protection request." }, "v1Protection": { "type": "object", "properties": { "id": { "type": "string", "description": "Protection ID." }, "resource_id": { "type": "string", "description": "Resource ID protected by the policy." }, "policy_id": { "type": "string", "description": "Policy ID applied by the protection." }, "job_id": { "type": "string", "description": "Job ID of the periodic (or one-off) schedule. Jobs spawn tasks." } }, "description": "Protection represents a policy applied to a resource." }, "v1ProtectionPage": { "type": "object", "properties": { "next_page_token": { "type": "string", "description": "Token for the next page in the listing operation. Set this value as `page_token` in the subsequent request. Empty on the last page." }, "items": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1Protection" }, "description": "List of protections." } }, "description": "ProtectionPage contains the results of listing protections." }, "v1Quota": { "type": "object", "properties": { "kind": { "type": "string", "description": "Kind of item covered by this quota (resource (user), storage, virtual machine, node, etc.)." }, "count": { "type": "string", "format": "int64", "description": "Maximum number of units allowed for this item." }, "units": { "type": "string", "description": "Unit of measure used for this quota (empty for resource/node quotas; MB or GB for storage)." } }, "description": "Quota describes the licensed limits for a specific item kind." }, "v1Resource": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the resource." }, "external_id": { "type": "string", "description": "External (Google Workspace, Microsoft 365, etc.) ID of the resource." }, "tenant_id": { "type": "string", "description": "Tenant that owns the resource." }, "name": { "type": "string", "description": "Resource name (for example, a user's email for Google Workspace or Microsoft 365 tenants, or the name of a Shared Drive)." }, "kind": { "type": "string", "description": "Resource kind (for example, office_user or office_teamdrive)." }, "archived": { "type": "boolean", "description": "Indicates whether the resource is archived. When true, the resource can no longer be backed up (for example, if it was deleted)." } }, "description": "Resource describes a single managed resource." }, "v1ResourcePage": { "type": "object", "properties": { "next_page_token": { "type": "string", "description": "Token for the next page in the listing operation. Set this value as `page_token` in the subsequent request. Empty on the last page." }, "items": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1Resource" }, "description": "List of resources." } }, "description": "ResourcePage contains the results of listing resources." }, "v1ResourceStats": { "type": "object", "properties": { "tenants": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1ResourceTenantStats" } } }, "description": "ResourceStats contains resource statistics per tenant." }, "v1ResourceStatsDetailedEntry": { "type": "object", "properties": { "kind": { "type": "string", "description": "Resource kind." }, "count": { "type": "integer", "format": "int32", "description": "Number of resources of this kind." }, "protected_count": { "type": "integer", "format": "int32", "description": "Number of protected resources of this kind." } }, "description": "ResourceStatsDetailedEntry contains statistics per resource kind." }, "v1ResourceStatsTotalEntry": { "type": "object", "properties": { "count": { "type": "integer", "format": "int32", "description": "Total count of resources." }, "protected_count": { "type": "integer", "format": "int32", "description": "Total count of protected resources." }, "size_total": { "type": "string", "format": "int64", "description": "Total resource storage, in KB." } }, "description": "ResourceStatsTotalEntry contains aggregated statistics for all resources." }, "v1ResourceTenantStats": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "Tenant ID that owns the resources." }, "kind": { "type": "string", "description": "Tenant kind (`gsuite` for Google Workspace, `o365` for Microsoft 365, etc.)." }, "name": { "type": "string", "description": "Tenant name." }, "resource_details": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1ResourceStatsDetailedEntry" }, "description": "Detailed resource statistics for the tenant, aggregated per resource kind." }, "resources_total": { "$ref": "#/definitions/v1ResourceStatsTotalEntry", "description": "Aggregated information about all tenant resources." } }, "description": "ResourceTenantStats represents resource statistics for a single tenant." }, "v1Subscription": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the subscription." }, "status": { "type": "string", "description": "Subscription status. Possible values include `trial`, `trial_expired`, `active`, `expired`, and `canceled`." }, "expires": { "type": "string", "format": "date-time", "description": "Expected time when the subscription expires or renews (for active subscriptions)." }, "tenant_id": { "type": "string", "description": "ID of the tenant the subscription is assigned to." }, "items": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1SubscriptionItem" }, "description": "Subscription items for billable item classes licensed by this subscription." }, "quotas": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1Quota" }, "description": "Quota limits this subscription grants to the tenant." } }, "description": "Subscription describes the status and details of a service subscription." }, "v1SubscriptionHistoryItem": { "type": "object", "properties": { "sub_id": { "type": "string", "description": "ID of the subscription." }, "tenant_id": { "type": "string", "description": "Tenant ID the subscription is assigned to." }, "start": { "type": "string", "format": "date-time", "description": "Start of the period. Use RFC 3339 format." }, "end": { "type": "string", "format": "date-time", "description": "End of the period. Use RFC 3339 format." }, "kind": { "type": "string", "description": "Subscription item kind (for example, resource, storage, node, virtual machine, or database)." }, "qty": { "type": "string", "format": "int64", "description": "Number of licensed units for the item kind (for example, 10 resources or 5 additional storage licenses, each granting 100 GB of quota)." }, "amount": { "type": "string", "format": "int64", "description": "Total amount, in cents, billed for this item during the corresponding interval.\nThis amount can change if the pricing plan changes mid-billing period (before the invoice is issued)." } }, "description": "SubscriptionHistoryItem represents a time span during which the licensed\nsubscription item quantity remains constant." }, "v1SubscriptionHistoryResult": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1SubscriptionHistoryItem" } } }, "description": "SubscriptionHistoryResult is the response to a subscription history request." }, "v1SubscriptionItem": { "type": "object", "properties": { "kind": { "type": "string", "description": "Subscription item kind (for example, resource, storage, node, virtual machine, or database)." }, "qty": { "type": "string", "format": "int64", "description": "Number of licensed units for the billable item kind (for example, 10 resources or 5 additional storage licenses, each granting 100 GB of quota)." }, "auto_license": { "type": "boolean", "description": "Indicates whether the service automatically adjusts this subscription item based on current consumption. An administrator configures this setting." }, "auto_license_max": { "type": "string", "format": "int64", "description": "Maximum quantity that the automatic license adjustment procedure can set. An administrator configures this limit." } }, "description": "SubscriptionItem describes subscription details for a specific billable item kind (resource (user), storage, virtual machine, node, etc.)." }, "v1SubscriptionsPage": { "type": "object", "properties": { "next_page_token": { "type": "string", "description": "Token for the next page in the listing operation. Set this value as `page_token` in the subsequent request. Empty on the last page." }, "items": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1Subscription" }, "description": "List of subscriptions that match the request." } }, "description": "SubscriptionsPage contains the results of listing subscriptions." }, "v1Task": { "type": "object", "properties": { "id": { "type": "string", "description": "Task ID." }, "resource_id": { "type": "string", "description": "ID of the resource with which the task is associated." }, "status": { "type": "string", "description": "Task status. Valid values: `open`, `inprogress`, `done`, `failed`, `suspended`, `warnings`, `canceled`.\nThe `done`, `failed`, `warnings`, and `canceled` statuses are terminal.\nThe `warnings` status indicates that the task completed with warnings that might require attention." } }, "description": "Task describes a single task." }, "v1TaskStatusStats": { "type": "object", "properties": { "done": { "type": "integer", "format": "int32" }, "failed": { "type": "integer", "format": "int32" }, "warnings": { "type": "integer", "format": "int32" } } }, "v1TaskTenantStats": { "type": "object", "properties": { "total": { "$ref": "#/definitions/v1TaskStatusStats" }, "by_action": { "type": "object", "additionalProperties": { "$ref": "#/definitions/v1TaskStatusStats" } } } }, "v1Tenant": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the tenant." }, "external_id": { "type": "string", "description": "External (Google Workspace, Microsoft 365, etc.) ID of the tenant." }, "kind": { "type": "string", "description": "Tenant kind (`gsuite` for Google Workspace, `o365` for Microsoft 365, etc.)." }, "name": { "type": "string", "description": "Tenant name. For Google Workspace and Microsoft 365 tenants, this is typically the domain name." }, "region": { "type": "string", "description": "Region where the tenant resides. Two-letter country or territory code in accordance with ISO 3166-1 alpha-2 (for example, US, CA, AU, UK, EU)." }, "deleted": { "type": "boolean", "description": "True if the tenant has been terminated and can no longer be queried. Deleted tenant subscriptions use the `canceled` state." } }, "description": "Tenant describes a single tenant." }, "v1TenantQuota": { "type": "object", "properties": { "kind": { "type": "string", "description": "Kind of item covered by this quota (resource (user), storage, virtual machine, node, etc.)." }, "used": { "type": "string", "format": "uint64", "description": "Number of quota units consumed." }, "limit": { "type": "string", "format": "uint64", "description": "Maximum number of units allowed for this item.\nIf automatic license quantity adjustment is enabled, this limit equals the auto-licensing limit.\nA value of 4294967295 means unlimited." }, "units": { "type": "string", "description": "Unit of measure used for this quota (empty for resource, virtual machine, database, and node quotas; MB or GB for storage)." }, "exceeded": { "type": "boolean", "description": "Indicates whether the quota limit is exceeded. Once exceeded, the service becomes restricted and some or all backups may fail." } }, "description": "TenantQuota describes tenant usage and quota limits for a given quota kind." }, "v1TenantQuotas": { "type": "object", "properties": { "quotas": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1TenantQuota" } } }, "description": "TenantQuotas contains the quota entries for a tenant." }, "v1TenantsPage": { "type": "object", "properties": { "next_page_token": { "type": "string", "description": "Token for the next page in the listing operation. Set this value as `page_token` in the subsequent request. Empty on the last page." }, "items": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1Tenant" }, "description": "List of tenants." } }, "description": "TenantsPage contains the results of listing organization tenants." }, "v1TriggerJobResult": { "type": "object", "properties": { "task_id": { "type": "string", "description": "ID of the task spawned by the job. Use it to monitor the task status." } }, "description": "TriggerJobResult contains the result of triggering a job." } }, "securityDefinitions": { "ApplicationAuthKey": { "type": "apiKey", "name": "Authorization", "in": "header" } }, "security": [ { "ApplicationAuthKey": [] } ] }