openapi: 3.0.3 info: title: APIsec Platform API version: 1.0.0 description: 'The APIsec Platform API lets you automate what you do in the APIsec console: onboard APIs as applications, configure authentication for each environment, run scans, and pull the resulting detections into your pipeline or ticketing system. **Authentication.** Every request needs an API credential in the `Authorization` header: `Authorization: Bearer `. Use either a Personal Access Token or an OAuth access token from `POST /v1/usersmanagement/oauth/token`. Both work with every operation listed here. Each operation lists the roles it needs, and its scope where one applies. See [API credentials](/docs/api-token). **Environments and instances.** The console calls the deployment you scan an *environment*. The API paths and IDs call it an `instance`.' contact: name: APIsec email: support@apisec.ai license: name: Proprietary. Copyright APIsec. url: https://www.apisec.ai servers: - url: https://api.apisecapps.com security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'A Personal Access Token, or an access token obtained from `POST /v1/usersmanagement/oauth/token`. Sent as `Authorization: Bearer `.' parameters: ApplicationId: name: applicationId in: path required: true description: Application identifier (UUID). schema: type: string InstanceId: name: instanceId in: path required: true description: Instance identifier. An instance is called an environment in the console. schema: type: string NextToken: name: nextToken in: query required: false description: Opaque pagination token returned by a previous call. schema: type: string responses: BadRequest: description: The request is invalid. The `message` field in the response body says which part to fix. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: The API credential is missing, malformed, expired or revoked. The body is the plain text `Unauthorized`, not JSON. content: text/plain: schema: type: string example: Unauthorized Forbidden: description: Your API credential is valid but does not permit this operation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: The resource does not exist, or it is not visible to your API credential. Both cases return the same response. Check the ID, and check that the application is shared with you or with one of your teams. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Conflict: description: The request conflicts with the current state of the resource. The `message` field in the response body explains the conflict. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' schemas: ErrorResponse: type: object description: The error body returned by most operations when a request fails. properties: status: type: string description: The HTTP reason phrase, for example `Bad Request` or `Not Found`. message: type: string description: What went wrong, in plain language. Show it to the user or log it. correlationId: type: string description: An ID for this request that APIsec support can trace. Present on some errors only; include it when you contact support. MemberType: type: string description: The kind of member an application is shared with. Only `TEAM` is supported. enum: - TEAM UsagePermissions: type: string description: 'The access a team gets to a shared application: `View` lets members see it; `Edit` also lets them change it, for example rename it or reload its spec.' enum: - View - Edit CredentialParam: type: object description: One credential value, and the field name your API expects it under. properties: providerKey: type: string description: The field name your login or token endpoint expects for this value, for example `email`, `username`, or `client_id`. credentialValue: type: string description: The secret value. Masked or omitted in responses. AuthCredentials: type: object description: The credential values APIsec uses to sign in. Which entries you need depends on the authentication type. API Key and HMAC carry their secrets in `authScheme` and need no entries here. properties: username: allOf: - $ref: '#/components/schemas/CredentialParam' description: The username or email. Used by Bearer Token and Basic. password: allOf: - $ref: '#/components/schemas/CredentialParam' description: The password. Used by Bearer Token and Basic. clientId: allOf: - $ref: '#/components/schemas/CredentialParam' description: The OAuth client ID. Used by OAuth 2.0. clientSecret: allOf: - $ref: '#/components/schemas/CredentialParam' description: The OAuth client secret. Used by OAuth 2.0. AuthSchemeRequestPlacement: type: object description: Where a value goes on a request (`in`), and its name or content (`key`). properties: in: type: string description: Where the value is placed, for example `header`, `Body`, or `queryParameter`. key: type: string description: The name of the header or field, or its value, depending on the property. Where several `key:value` pairs are allowed, separate them with commas and no spaces, for example `X-Tenant:acme,X-Region:eu`. AuthProvider: type: object description: The endpoint APIsec calls to obtain a credential for Bearer Token and OAuth 2.0, and the type selector for the credential request. properties: scheme: type: string description: 'Must match the authentication type exactly: `bearerToken` for Bearer Token (`HTTP` or `bearerToken`), `basic` for Basic, `oauth2` for OAuth 2.0. Case-sensitive.' discoveryUrl: type: string description: Reserved. Send an empty string. authUrl: type: string description: The endpoint APIsec calls to sign in. For Bearer Token, your login endpoint. For OAuth 2.0, your **token** endpoint, not the authorization endpoint. Not needed for Basic. tokenUrl: type: string description: Reserved. Send an empty string. For OAuth 2.0, put the token endpoint in `authUrl`. HmacConfig: type: object description: How APIsec signs each scanned request when the authentication type is `hmac`. properties: algorithm: type: string example: HS256 description: The signing algorithm, for example `HS256`. Required. signedComponents: type: array items: type: string description: The parts of the request included in the signature, for example `["body"]`. Required; must not be empty. bodyHashFormat: type: string example: raw description: How the body is represented before signing, for example `raw`. Optional. outputEncoding: type: string example: hex description: How the signature is encoded, for example `hex`. Required. signatureField: allOf: - $ref: '#/components/schemas/AuthSchemeRequestPlacement' description: 'Where the signature is sent, for example `{"in": "header", "key": "webhook-signature"}`. Both `in` and `key` are required.' AuthScheme: type: object description: How APIsec authenticates to the API under test. `type` selects the authentication type, and determines which other properties apply. properties: type: type: string description: 'The authentication type. Case-sensitive. `HTTP` or `bearerToken`: Bearer Token, where APIsec signs in at a login endpoint and sends the returned token. `basic`: HTTP Basic. `oauth2`: OAuth 2.0 client credentials grant. `apikey`: one or more static headers or query parameters. `hmac`: a signature on each request. `authChain`: a Custom Authentication flow that APIsec sets up for you; contact APIsec support.' enum: - bearerToken - HTTP - oauth2 - basic - apikey - authChain - hmac placement: allOf: - $ref: '#/components/schemas/AuthSchemeRequestPlacement' description: 'Where the resolved credential is sent on scanned requests, for example `{"in": "header", "key": "Authorization"}`.' contentType: allOf: - $ref: '#/components/schemas/AuthSchemeRequestPlacement' description: For Bearer Token, how the login request is encoded. Set `key` to `application/json`, or to `application/x-www-form-urlencoded` to post a form. grantType: allOf: - $ref: '#/components/schemas/AuthSchemeRequestPlacement' description: OAuth 2.0 only. Set `key` to `client_credentials`, the only supported grant. scope: allOf: - $ref: '#/components/schemas/AuthSchemeRequestPlacement' description: OAuth 2.0 only. The scope to request from your token endpoint, in `key`. Leave `key` empty to request no scope. audience: allOf: - $ref: '#/components/schemas/AuthSchemeRequestPlacement' description: OAuth 2.0 only. The audience to request from your token endpoint, in `key`. Leave `key` empty if your provider does not need one. additionalHeaders: allOf: - $ref: '#/components/schemas/AuthSchemeRequestPlacement' description: 'Extra headers sent to the login endpoint, as comma-separated `name:value` pairs in `key`. For Bearer Token, include this object even when you have no extra headers: `{"in": "Header", "key": ""}`.' additionalBodyParameters: allOf: - $ref: '#/components/schemas/AuthSchemeRequestPlacement' description: Extra fields sent in the login request body, as comma-separated `name:value` pairs in `key`. responseKey: allOf: - $ref: '#/components/schemas/AuthSchemeRequestPlacement' description: Where the credential is found in the sign-in response. `key` is the field name, for example `token` or `access_token`; use a dotted path for a nested field. apiKey: allOf: - $ref: '#/components/schemas/AuthSchemeRequestPlacement' description: API Key only. `key` holds one or more `name:value` pairs, comma-separated with no spaces, for example `X-API-Key:abc123,X-Tenant:acme`. Each pair is sent on every scanned request. Values cannot contain commas. Set `in` to `queryParameter` to send the pairs as query parameters; any other value sends them as headers. authProviderList: type: array items: $ref: '#/components/schemas/AuthProvider' description: The endpoint APIsec calls to obtain the credential. Send exactly one entry. Required for Bearer Token, Basic, and OAuth 2.0. customAuthChainId: type: string description: Custom Authentication only. The ID of the authentication flow APIsec set up for you. Required when `type` is `authChain`. tokenTTL: type: integer description: How often, in minutes, APIsec signs in again to get a fresh credential during a scan. The console calls this **Token Renewal Frequency**. Minimum 5. hmac: allOf: - $ref: '#/components/schemas/HmacConfig' description: HMAC only. The signing configuration. Required when `type` is `hmac`. hmacKey: type: string description: HMAC only. The shared secret used to sign requests. Required and must not be blank when `type` is `hmac`. AuthenticationConfig: type: object description: 'An authentication configuration: a named way for APIsec to sign in to the API under test. The console calls these **Credentials**.' properties: name: type: string description: A name for the configuration, unique within the environment. Appears in the console and as `scanAuth` on scans that use it. authScheme: allOf: - $ref: '#/components/schemas/AuthScheme' description: The authentication type and how to obtain and send the credential. credentials: allOf: - $ref: '#/components/schemas/AuthCredentials' description: The credential values. Which entries you need depends on the type. isDefault: type: boolean description: Set `true` to make this the environment's default credential. In responses this field is named `default`. role: type: string description: Optional label for the identity this credential represents, for example `admin` or `user-a`. ResponseInfo: type: object description: 'An HTTP response captured during a credential test: whether the host was reachable, the response headers, and the response body. Credential values in the body are masked.' additionalProperties: true TestAuthenticationResponse: type: object description: The result of a credential test. Check `valid` first; the remaining fields show what happened at each step. properties: method: type: string description: The HTTP method of the endpoint called with the resolved credential. endpoint: type: string description: The endpoint called with the resolved credential. responseStatusCode: type: integer description: The HTTP status that endpoint returned. valid: type: boolean description: '`true` if the test passed. This is the pass/fail result.' authResolvedResponse: allOf: - $ref: '#/components/schemas/ResponseInfo' description: The response from the sign-in step, such as your login or token endpoint. Credential values are masked. authResolvedResponseStatusCode: type: integer description: The HTTP status your login or token endpoint returned. authResolvedUrl: type: string description: The URL APIsec called to sign in. responseInfo: allOf: - $ref: '#/components/schemas/ResponseInfo' description: The response from the endpoint called with the resolved credential. authChain: type: string description: Custom Authentication only. Null for other types. HostedAgentStatus: type: string description: 'The state of a hosted agent. `PROVISIONED`: created, but no container has reported in yet, or the token was rotated and no container has started with the new one. `ACTIVE`: a container has reported in and is sending heartbeats; only an `ACTIVE` agent runs scans. `UNRESPONSIVE`: an active agent has not sent a heartbeat for at least an hour. `SHUTDOWN`: the agent stopped gracefully. `DELETED`: the agent was deleted and its token revoked.' enum: - PROVISIONED - ACTIVE - UNRESPONSIVE - SHUTDOWN - DELETED HostedAgentHostingScope: type: string description: 'Who can use the agent. `SHARED`: created with an ADMIN credential and available across your tenant. `PRIVATE`: available only to the user who created it.' enum: - SHARED - PRIVATE HostedAgentDeploymentType: type: string description: 'The kind of host the agent''s install command targets: `DOCKER_LINUX` (a bash script for Docker on Linux) or `DOCKER_WINDOWS` (a PowerShell script for Docker on Windows). For Kubernetes, see [Deploy on Kubernetes](/docs/Hosted-Agents/deploy-kubernetes).' enum: - DOCKER_LINUX - DOCKER_WINDOWS CreateHostedAgentRequest: type: object required: - name properties: name: type: string description: A display name for the agent, shown in the console's **Hosted Agents** table. description: The details of a new hosted agent. CreateHostedAgentResponse: type: object properties: id: type: string format: uuid description: The new agent's ID. Pass it to `getHostedAgentDownloadCommand` to get the install command. description: The result of creating a hosted agent. GetAgentsResponse: type: object properties: agents: type: array items: $ref: '#/components/schemas/HostedAgentInfo' description: One summary entry per agent. description: The hosted agents visible to you. HostedAgentInfo: type: object description: A summary of one hosted agent. properties: id: type: string format: uuid description: The agent's ID. name: type: string description: The agent's display name. type: allOf: - $ref: '#/components/schemas/HostedAgentDeploymentType' description: The kind of host the agent's install command targets. version: type: string description: The version the agent reports, as shown in the console. status: allOf: - $ref: '#/components/schemas/HostedAgentStatus' description: The agent's current state. Only `ACTIVE` agents run scans. createdAt: type: string description: When the agent was created. latestHeartbeat: type: string nullable: true description: When the agent last sent a heartbeat. Null until a container first reports in. usageRole: type: string description: Your relationship to the agent, such as `OWNER` (you created it) or `COLLABORATOR`. Handle unrecognized values gracefully. tokenExpiresAt: type: string nullable: true description: When the agent's current token expires. Null if no token has been issued. hostingScope: allOf: - $ref: '#/components/schemas/HostedAgentHostingScope' description: Whether the agent is shared across your tenant or private to its creator. PrivateAgent: type: object description: The full record of one hosted agent. properties: id: type: string format: uuid description: The agent's ID. data: allOf: - $ref: '#/components/schemas/HostedAgentData' description: 'The agent''s current state: name, status, version, heartbeat, host type, and token expiry.' createdAt: type: string description: When the agent was created. createdBy: type: string description: The user ID of the agent's creator. usageRole: type: string description: Your relationship to the agent, such as `OWNER` (you created it) or `COLLABORATOR`. Handle unrecognized values gracefully. hostingScope: allOf: - $ref: '#/components/schemas/HostedAgentHostingScope' description: Whether the agent is shared across your tenant or private to its creator. HostedAgentData: type: object description: The current state of a hosted agent. properties: name: type: string description: The agent's display name. status: allOf: - $ref: '#/components/schemas/HostedAgentStatus' description: The agent's current state. Only `ACTIVE` agents run scans. version: type: string description: The version the agent reports, as shown in the console. lastHeartbeat: type: string nullable: true description: When the agent last sent a heartbeat. Null until a container first reports in, and again after a token rotation. type: allOf: - $ref: '#/components/schemas/HostedAgentDeploymentType' description: The kind of host the agent's install command targets. tokenExpiresAt: type: string nullable: true description: When the agent's current token expires. Null if no token has been issued. HostedAgentDisplay: type: object description: A hosted agent's ID and display name, for labelling. properties: id: type: string description: The agent's ID, as requested. name: type: string description: The agent's display name. An empty string if the agent has no name. Team: type: object description: A team within a business unit, with its owner and, when you get a single team, its members. properties: teamId: type: string description: The team's ID. teamName: type: string description: The team's name, as shown in the console. businessUnitId: type: string description: The ID of the business unit the team belongs to. businessUnitName: type: string description: The name of the business unit the team belongs to. ownerId: type: string description: The user ID of the team owner. ownerEmail: type: string description: The email address of the team owner. members: type: array items: $ref: '#/components/schemas/TeamMember' description: The team's members and their permissions. Present when you get a single team; null in the list of teams. createdAt: type: string format: date-time description: When the team was created, in ISO 8601 format. Can be null. TeamMember: type: object description: One member of a team and the permission they hold on the team's applications. required: - member - permission properties: member: type: string description: The member's user ID. memberEmail: type: string nullable: true description: The member's email address. Can be null. permission: $ref: '#/components/schemas/TeamPermissions' memberRole: type: string nullable: true description: The member's platform role, such as `ADMIN`, `USER` or `VIEWER`. Null when not available. TeamPermissions: type: string description: 'The permission a team member holds on the team''s applications. `View` gives read-only access. `Edit` also allows changes such as triaging detections and configuring the issue tracker. Values are case-sensitive: `View` and `Edit`.' enum: - View - Edit UserMembership: type: object description: One team a user belongs to and the permission they hold in it. properties: teamId: type: string description: The team's ID. teamName: type: string description: The team's name. permission: allOf: - $ref: '#/components/schemas/TeamPermissions' description: 'The user''s permission on the team''s applications: `View` or `Edit`.' GetTeamsForUserResponse: type: object description: A user's team memberships. properties: membership: type: array items: $ref: '#/components/schemas/UserMembership' description: The teams the user belongs to. Empty when the user is in no team. ListTeamsResponse: type: object description: The teams visible to your credential. properties: teams: type: array nullable: true description: The teams. Each entry omits its member list; get a single team to see members. items: $ref: '#/components/schemas/Team' MessageResponse: type: object description: A confirmation message. properties: message: type: string description: Human-readable result of the operation. RegisterApplicationResponse: type: object properties: applicationId: type: string description: ID of the application. Use it in every later call for this application. hostUrls: type: array items: type: string description: Host URLs of the environments created from the source. Can be empty, for example when the source has no server URL; add an environment yourself in that case. malformedHostUrls: type: array items: type: string description: Server URLs in the source that were not used because they lack a scheme or host. Fix them in the spec, or add the environment yourself. externalId: type: string description: The external ID you sent, if any. qualifier: type: string description: The qualifier you sent, if any. created: type: boolean description: '`true` when this call created the application; `false` when it returned an existing application with the same external ID and qualifier.' instances: type: array items: $ref: '#/components/schemas/ExternalInstanceSummary' description: The application's environments, with their IDs and host URLs. name: type: string description: Display name of the application. description: The result of registering an application. ExternalInstanceSummary: type: object properties: instanceId: type: string description: ID of the environment (`instanceId` in paths). instanceName: type: string description: Display name of the environment. Can be empty. hostUrl: type: string description: Base URL of the deployment the environment points at. description: An environment of an application found by external ID. RenameApplicationRequest: type: object required: - newName properties: newName: type: string description: The new display name. description: The new name for an application. RenameApplicationResponse: type: object properties: message: type: string description: Human-readable result of the operation. applicationId: type: string description: ID of the renamed application. applicationName: type: string description: The application's new display name. description: Confirmation of an application rename. ApiGatewayDetails: type: object properties: action: type: string enum: - LINK - UNLINK description: '`LINK` to connect the application to the gateway API, or `UNLINK` to remove the connection.' integrationType: type: string description: The gateway or platform the application is linked to. integrationId: type: string description: ID of the gateway integration. integrationName: type: string description: Display name of the gateway integration. awsRequest: type: object additionalProperties: true description: Details for an AWS API Gateway API. Fields depend on the platform. azureRequest: type: object additionalProperties: true description: Details for an Azure API Management API. Fields depend on the platform. muleSoft: type: object additionalProperties: true description: Details for a MuleSoft API. Fields depend on the platform. swaggerHub: type: object additionalProperties: true description: Details for a SwaggerHub API. Fields depend on the platform. postmanRequest: type: object additionalProperties: true description: Details for a Postman collection. Fields depend on the platform. description: Links an application to, or unlinks it from, an API in a gateway or API management platform. Supply the details object for your platform only. GetReloadDiffResponse: type: object properties: applicationId: type: string description: ID of the application. instanceId: type: string description: ID of the environment. addedEndpointCount: type: integer description: Number of endpoints the new spec added. removedEndpointCount: type: integer description: Number of endpoints the new spec removed. status: type: string description: 'Outcome of the reload: `Success` or `Failed`.' timestamp: type: string description: When the reload finished, as an ISO 8601 UTC timestamp. manifestAvailable: type: boolean description: '`true` when the response includes the lists of added and removed endpoints.' addedEndpoints: type: array nullable: true items: $ref: '#/components/schemas/EndpointSummary' description: Endpoints present in the new spec but not the previous one. Null when `manifestAvailable` is `false`. removedEndpoints: type: array nullable: true items: $ref: '#/components/schemas/EndpointSummary' description: Endpoints present in the previous spec but not the new one. Null when `manifestAvailable` is `false`. description: What the most recent spec reload changed in an environment. EndpointSummary: type: object properties: id: type: string description: ID of the endpoint, as used by the Endpoints calls. method: type: string description: HTTP method, for example `GET`. path: type: string description: Path of the endpoint, relative to the environment's host URL. description: An endpoint, identified by method and path. InstanceIssueTrackerConfigPayloadRequest: type: object properties: connectionId: type: string description: The ID of an issue tracker connection created in the console under **Integrations** › **Issue Tracker**. projectKey: type: string description: Where tickets go in the issue tracker. For Jira, the project key. For Azure DevOps, the project name. For ServiceNow, your ServiceNow instance URL, such as `https://example.service-now.com`. issueTrackerName: type: string description: 'The type of issue tracker the connection belongs to: `JIRA`, `AZURE_DEVOPS` or `SERVICENOW`.' syncIssues: type: boolean description: When `true`, APIsec creates tickets automatically for new detections after each scan. Tickets that already exist are closed and reopened as their detections change status, whatever this is set to. description: 'The issue tracker settings for an environment: which connection to use, where tickets go and whether they are created automatically.' AutoReloadSpecSchedule: type: object properties: applicationId: type: string description: ID of the application. instanceId: type: string description: ID of the environment. origin: type: string description: The gateway or platform the spec is reloaded from. reloadSpecConfig: type: object additionalProperties: true description: Reload options applied on each run. Fields depend on the platform. apiGatewayDetails: allOf: - $ref: '#/components/schemas/ApiGatewayDetails' description: The gateway API the spec is reloaded from. scheduleName: type: string description: Name of the schedule. scheduleId: type: string description: ID of the schedule. frequency: type: string description: How often the reload runs, for example weekly. time: type: string description: Time of day the reload runs, in `timeZone`. dayOfWeek: type: string description: Day of the week the reload runs, for weekly schedules. timeZone: type: string description: Time zone for `time` and `dayOfWeek`. nextExecutionOn: type: string description: When the next reload is due. enabled: type: boolean description: '`true` when auto-reload is turned on; `false` when it is paused.' description: The schedule on which APIsec reloads an environment's spec from its linked API gateway. MetadataTagOption: type: object properties: optionId: type: string description: ID of the value. Use it to assign the value to environments. label: type: string description: Display text of the value. sortOrder: type: integer description: Position of the value in the field's list, starting from the first option sent. description: One allowed value of a metadata tag field. MetadataTagOptionInput: type: object required: - label properties: optionId: type: string nullable: true description: ID of an existing value to keep. Omit or send null to add a new value. label: type: string description: Display text of the value. description: A value of a metadata tag field, as you send it when creating or replacing the field. MetadataTagRecord: type: object properties: tagId: type: string description: ID of the field. label: type: string description: Display name of the field, for example `Data Classification`. options: type: array items: $ref: '#/components/schemas/MetadataTagOption' description: The field's allowed values, in display order. instanceCount: type: integer description: Number of environments with at least one of the field's values assigned. You can delete the field only when this is 0. updatedBy: type: string nullable: true description: The user who last changed the field. Null if it has not been changed since it was created. updatedAt: type: string nullable: true description: When the field was last changed, as an ISO 8601 timestamp. Null if it has not been changed since it was created. description: A tenant-wide metadata tag field and its allowed values. MetadataTagListResponse: type: object properties: tags: type: array items: $ref: '#/components/schemas/MetadataTagRecord' description: The tenant's metadata tag fields. description: All metadata tag fields in the tenant. CreateMetadataTagRequest: type: object required: - label - options properties: label: type: string description: Display name of the field. options: type: array minItems: 1 maxItems: 50 items: $ref: '#/components/schemas/MetadataTagOptionInput' description: The field's allowed values, 1 to 50, in display order. description: A new metadata tag field. UpdateMetadataTagRequest: type: object required: - label - options properties: label: type: string description: New display name of the field. options: type: array minItems: 1 maxItems: 50 items: $ref: '#/components/schemas/MetadataTagOptionInput' description: The complete list of allowed values, 1 to 50, in display order. Include each value to keep with its `optionId`. description: The complete new definition of a metadata tag field. Existing values you leave out are deleted and unassigned from every environment. MetadataTagDeleteAck: type: object description: Confirmation that a metadata tag field was deleted. properties: tagId: type: string description: ID of the deleted field. message: type: string description: Human-readable result of the operation. MetadataTagInstanceAssignment: type: object properties: applicationId: type: string description: ID of the application. instanceId: type: string description: ID of the environment. optionIds: type: array items: type: string description: IDs of the field's values assigned to this environment. description: An environment that has values of a metadata tag field assigned. MetadataTagInstancesResponse: type: object properties: instances: type: array items: $ref: '#/components/schemas/MetadataTagInstanceAssignment' description: The environments on this page. nextToken: type: string nullable: true description: Token for the next page. Null on the last page. description: A page of environments that have a metadata tag field assigned. MetadataTagAssignmentTarget: type: object required: - applicationId - instanceId properties: applicationId: type: string description: ID of the application. instanceId: type: string description: ID of the environment. description: An environment to update, identified by application and environment ID. UpdateInstanceMetadataTagValuesRequest: type: object required: - targets - values properties: targets: type: array minItems: 1 items: $ref: '#/components/schemas/MetadataTagAssignmentTarget' description: The environments to update. At least one. values: type: object minProperties: 1 maxProperties: 20 additionalProperties: type: array nullable: true items: type: string description: Map of `tagId` to the list of `optionId` values to assign to every target. A null or empty list clears that field. From 1 to 20 fields per request; fields you leave out are not changed. description: Metadata tag values to set or clear on a set of environments. MetadataTagValueUpdateFailure: type: object properties: applicationId: type: string description: ID of the application. instanceId: type: string description: ID of the environment. reason: type: string description: Why the update failed for this environment. description: An environment that could not be updated. UpdateInstanceMetadataTagValuesResponse: type: object properties: updatedCount: type: integer description: Number of environments updated. updatedTargets: type: array items: $ref: '#/components/schemas/MetadataTagAssignmentTarget' description: The environments that were updated. failedTargets: type: array items: $ref: '#/components/schemas/MetadataTagValueUpdateFailure' description: The environments that were not updated, each with a reason. Empty when every update succeeded. description: The outcome of a bulk metadata tag update, per environment. MetadataTagOptionValue: type: object properties: optionId: type: string description: ID of the value. label: type: string description: Display text of the value. description: A metadata tag value assigned to an environment. ApplicationInstanceMetadataValue: type: object properties: tagId: type: string description: ID of the field. label: type: string description: Display name of the field. values: type: array items: $ref: '#/components/schemas/MetadataTagOptionValue' description: The field's values assigned to the environment. description: The values of one metadata tag field assigned to an environment. InstanceMetadataTagsResponse: type: object properties: applicationId: type: string description: ID of the application. instanceId: type: string description: ID of the environment. values: type: array items: $ref: '#/components/schemas/ApplicationInstanceMetadataValue' description: One entry per field with at least one value assigned. Fields with no value assigned are left out. description: The metadata tag values assigned to one environment. GetApplicationsResponse: type: object description: A page of applications you can access. additionalProperties: true properties: applications: type: array items: $ref: '#/components/schemas/ApplicationRecord' description: The applications on this page. nextToken: type: string nullable: true description: Token for the next page. Null or empty on the last page. ApplicationRecord: type: object description: An application, its environments (`instances`) with their assigned metadata tags, and your access to it (`entitlement`). Each environment's `latestScanStats` is filled in by List applications only; Get an application returns it as null. additionalProperties: true properties: applicationId: type: string description: ID of the application. applicationName: type: string description: Display name of the application. externalId: type: string description: Your external ID for the application, if one is set. ShareApplicationRequest: type: object description: The teams to share an application with. Send either `memberId` with `memberType`, or `members`. properties: memberId: type: string description: ID of the team to share with. memberType: allOf: - $ref: '#/components/schemas/MemberType' description: Must be `TEAM`. permission: allOf: - $ref: '#/components/schemas/UsagePermissions' description: 'The access to grant: `View` or `Edit`.' members: type: array items: type: object properties: memberId: type: string memberType: $ref: '#/components/schemas/MemberType' permission: $ref: '#/components/schemas/UsagePermissions' description: Several teams to share with, each with `memberId`, `memberType` and `permission`. GetScansResponse: type: object description: The scans of an environment that match the requested statuses, newest first. properties: scans: type: array items: $ref: '#/components/schemas/BasicScanInfo' description: One summary entry per scan, newest first. nextToken: type: string nullable: true description: Always null. Every matching scan is in this response. BasicScanInfo: type: object description: A summary of one scan. properties: scanId: type: string description: The scan's ID. Pass it to `getScan` for details and detections. startTime: type: string description: When the scan started. lastUpdateTime: type: string description: When the scan's record last changed. status: type: string description: The scan's status, in title case. `Processing` while running, then one of the terminal values `Complete`, `Failed`, or `Aborted`. This differs from the lowercase values the `status` query parameter takes. enum: - Processing - Complete - Failed - Aborted triggerSource: type: string nullable: true description: What started the scan, for example `MANUAL` (the console), `CI_CD` (an API credential), or `SCHEDULED` (a scan schedule). May be null. executionSummary: type: object properties: totalTestsExecuted: type: integer format: int64 totalTestsPassed: type: integer format: int64 nullable: true totalTestsFailed: type: integer format: int64 nullable: true totalTestsSkipped: type: integer format: int64 nullable: true newDetections: type: integer format: int64 detectionsResolved: type: integer format: int64 activeDetections: type: integer format: int64 description: Counts for the scan. `totalTestsExecuted`, `newDetections`, `detectionsResolved`, and `activeDetections` are always present. `totalTestsPassed`, `totalTestsFailed`, and `totalTestsSkipped` may be null, for example while the scan is still running. ScanProfileData: type: object description: A saved, reusable scan scope for one environment. required: - name - endpoints properties: id: type: string readOnly: true description: The profile's ID, assigned by APIsec. Ignored on input. name: type: string description: The profile's name, shown in the console. Required. endpoints: type: array items: type: string description: The IDs of the endpoints to scan. Required; at least one. authId: type: string nullable: true description: The ID of the authentication configuration scans with this profile use. Null or empty for an unauthenticated scan. agentId: type: string nullable: true description: The ID of the hosted agent that runs scans with this profile. Null or empty to let APIsec choose. categories: type: array items: type: string description: The test categories to run. `ALL` runs every category. InstanceScanScheduleWindowRequest: type: object description: 'A recurring scan schedule: when it runs, and what each run scans.' properties: frequency: type: string description: 'How often the scan runs: `daily`, `weekly`, or `monthly`. Not case-sensitive.' scheduleName: type: string description: A name for the schedule, shown in the console. time: type: string description: The time of day the scan starts, as `HH:mm` in 24-hour form, in `timeZone`. For example `22:00`. dayOfMonth: type: string description: Monthly schedules only. The day of the month to run, for example `21`. dayOfWeek: type: string description: Weekly schedules only. The day of the week to run, from `1` (Sunday) to `7` (Saturday). timeZone: type: string description: The time zone for `time`, as a UTC offset in the form `UTC +05:30` or `UTC -04:00`. scanWithAuthId: type: string description: The ID of the authentication configuration each run uses. Empty for an unauthenticated scan. scanWithAgent: type: string description: The ID of the hosted agent that runs each scan. Empty to let APIsec choose. endpoints: type: array items: type: string description: The IDs of the endpoints each run scans. categories: type: array items: type: string description: The test categories each run includes. `ALL` (case-insensitive) runs every category. UpdateDetection: type: object properties: status: type: string description: 'The new status: `FALSE_POSITIVE` or `RISK_ACCEPTED`. When you raise tickets for several detections at once, leave it unset.' comments: type: string description: Your reason or note. It is recorded with the detection's triage details and passed to its ticket, if there is one. riskAcceptedEndDate: type: string description: For `RISK_ACCEPTED`, the date the risk acceptance ends, as `YYYY-MM-DD` or `YYYY-MM-DDTHH:mm`. Shown with the detection's risk acceptance details. detectionIds: type: array items: type: string description: The detections to act on. When you update a single detection, this defaults to the detection in the path. cvssScore: type: number format: double nullable: true description: The new CVSS score, from 0 to 10. Used only when `updateCvss` is `true`. updateCvss: type: boolean description: Set to `true` to change the detection's CVSS score to `cvssScore` instead of changing its status. description: The detection-update request. Use it to mark detections as False Positive or Risk Accepted, to override a CVSS score, or to raise tickets for several detections. paths: /v1/hostedagents: get: operationId: listHostedAgents summary: List hosted agents tags: - Hosted Agents description: 'Returns the hosted agents you can use: agents you created, agents shared with you, and agents shared across your tenant. Call it to find an agent ID for `scanWithAgent`, a scan profile, or a default hosted agent, or to monitor agent health. An agent you can use for scanning reports `status` `ACTIVE`. Use `status` and `hostingScope` to narrow the result. **Access:** Roles: ADMIN, USER, VIEWER' parameters: - name: status in: query required: false description: Return only agents in this state, for example `ACTIVE`. schema: $ref: '#/components/schemas/HostedAgentStatus' - name: hostingScope in: query required: false description: Return only `SHARED` (tenant-wide) or only `PRIVATE` agents. schema: $ref: '#/components/schemas/HostedAgentHostingScope' responses: '200': description: The hosted agents visible to you, under `agents`. content: application/json: schema: $ref: '#/components/schemas/GetAgentsResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' post: operationId: createHostedAgent summary: Create a hosted agent tags: - Hosted Agents description: 'Creates a hosted agent record and returns its `id`. This is the first step of deploying an agent: next, call `getHostedAgentDownloadCommand` and run the command on a host inside your network. The agent shows `PROVISIONED` until its container starts and reports in, then `ACTIVE`. An agent created with an ADMIN credential is shared across your tenant; otherwise it is private to you. See [Hosted agent quickstart](/docs/Hosted-Agents/quickstart). **Access:** Roles: ADMIN, USER' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateHostedAgentRequest' description: '`name`: a display name for the agent.' responses: '200': description: Agent created. The body carries its `id`. content: application/json: schema: $ref: '#/components/schemas/CreateHostedAgentResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /v1/hostedagents/{agentId}: get: operationId: getHostedAgent summary: Get a hosted agent tags: - Hosted Agents description: 'Returns one hosted agent: its status, reported version, last heartbeat, and token expiry. Poll it after deployment to confirm the agent reaches `ACTIVE`, or check it when scans routed to the agent fail. **Access:** Roles: ADMIN, USER, VIEWER' parameters: - name: agentId in: path required: true description: The hosted agent's ID, from `listHostedAgents` or the create response. schema: type: string format: uuid responses: '200': description: The hosted agent. content: application/json: schema: $ref: '#/components/schemas/PrivateAgent' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' delete: operationId: deleteHostedAgent summary: Delete a hosted agent tags: - Hosted Agents description: 'Deletes a hosted agent and revokes its token, so its containers cannot reconnect. Only the agent''s owner can delete it. An `ACTIVE` agent cannot be deleted: stop its containers first and wait until it shows `SHUTDOWN` or `UNRESPONSIVE`. Deleting an agent that is already deleted returns `200`. Every response body on this operation is a plain JSON string, not an object. **Access:** Roles: ADMIN, USER' parameters: - name: agentId in: path required: true description: The hosted agent's ID, from `listHostedAgents`. schema: type: string format: uuid responses: '200': description: Deleted. The body is `Agent deleted successfully`, or `Agent already marked for deletion` if it was already deleted. content: application/json: schema: type: string '400': description: The agent is `ACTIVE`. Stop its containers, then try again. The body is `Cannot delete an ACTIVE agent`. content: application/json: schema: type: string '401': $ref: '#/components/responses/Unauthorized' '403': description: You are not the agent's owner. The body is `You are not authorized to delete this agent`. content: application/json: schema: type: string '404': description: No such agent. The body is `Agent not found`. content: application/json: schema: type: string /v1/hostedagents/{agentId}/display: get: operationId: getHostedAgentDisplay summary: Get a hosted agent's name tags: - Hosted Agents description: 'Returns only a hosted agent''s ID and display name. Use it to label an agent ID that appears elsewhere, such as `agentId` on a scan or a scan profile. **Access:** Roles: ADMIN, USER, VIEWER' parameters: - name: agentId in: path required: true description: The hosted agent's ID. schema: type: string format: uuid responses: '200': description: The agent's ID and name. content: application/json: schema: $ref: '#/components/schemas/HostedAgentDisplay' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/hostedagents/{agentId}/download: get: operationId: getHostedAgentDownloadCommand summary: Get a hosted agent's install command tags: - Hosted Agents description: 'Returns a ready-to-run command that installs and starts the agent''s container. Run it on a host inside your network. The response is `text/plain`, and the body is the command itself. The command embeds the agent''s access token, so treat it as a secret. While the agent''s current token has not expired, downloading the command again does not interrupt containers already running. Re-download the command to upgrade the agent to a newer image. Only the agent''s owner can download it, or an ADMIN when the agent is shared across the tenant. See [Upgrading and versions](/docs/Hosted-Agents/upgrading). **Access:** Roles: ADMIN, USER, VIEWER' parameters: - name: agentId in: path required: true description: The hosted agent's ID. schema: type: string format: uuid - name: type in: query required: false description: 'The host the command is for: `DOCKER_LINUX` or `DOCKER_WINDOWS`. Always send it.' schema: $ref: '#/components/schemas/HostedAgentDeploymentType' responses: '200': description: The install command, as plain text. content: text/plain: schema: type: string '401': $ref: '#/components/responses/Unauthorized' '403': description: You are not the agent's owner, and the agent is not shared with ADMINs across the tenant. The body is `You are not authorized to download this agent.` content: text/plain: schema: type: string '404': $ref: '#/components/responses/NotFound' /v1/hostedagents/{agentId}/rotate-token: post: operationId: rotateHostedAgentToken summary: Rotate a hosted agent's token tags: - Hosted Agents description: 'Issues a new access token for the agent and returns an install command that carries it. Rotate when a token may have been exposed or an agent must be cut off. The agent returns to `PROVISIONED` until a container starts with the new command, so plan to redeploy every container for this agent together. To renew a token that is about to expire, re-download the install command with `getHostedAgentDownloadCommand` instead. The response is `text/plain`, and the body is the command itself. Only the agent''s owner can rotate its token, or an ADMIN when the agent is shared across the tenant. **Access:** Roles: ADMIN, USER' parameters: - name: agentId in: path required: true description: The hosted agent's ID. schema: type: string format: uuid - name: type in: query required: false description: 'The host the command is for: `DOCKER_LINUX` or `DOCKER_WINDOWS`. Defaults to the agent''s current type.' schema: $ref: '#/components/schemas/HostedAgentDeploymentType' responses: '200': description: The install command carrying the new token, as plain text. content: text/plain: schema: type: string '401': $ref: '#/components/responses/Unauthorized' '403': description: You are not the agent's owner, and the agent is not shared with ADMINs across the tenant. The body is `You are not authorized to rotate this agent's token.` content: text/plain: schema: type: string '404': $ref: '#/components/responses/NotFound' /v1/usersmanagement/teams/{teamId}: get: operationId: getTeam summary: Get a team tags: - Teams description: 'Returns one team with its business unit, owner and members, including each member''s **View** or **Edit** permission. Use it to check who is on a team and what they can do with the team''s applications. An ADMIN credential can read any team. Other credentials can read only teams they own or belong to. Get `teamId` from the list of teams. **Access:** Scope: `team:get` · Roles: ADMIN, USER' parameters: - name: teamId in: path required: true description: The team's ID, from `teamId` in the list of teams. schema: type: string responses: '200': description: The team, with its member list. content: application/json: schema: $ref: '#/components/schemas/Team' '400': description: The request could not be completed. The `message` field in the response body explains why. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: The team is not found or not visible to you. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/usersmanagement/teams: get: operationId: listTeamsForUser summary: List a user's teams tags: - Teams description: 'Returns the teams a user belongs to and the permission they hold in each. By default it returns your own memberships, which tells you which teams'' applications your credential can reach. An ADMIN credential can pass `memberId` to look up another user in the tenant. Other credentials get `403` if `memberId` names anyone but themselves. **Access:** Scope: `team:get` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - name: memberId in: query required: false description: The user ID whose teams to return. Omit it to return your own. Only an ADMIN credential can look up another user. schema: type: string responses: '200': description: The user's team memberships. content: application/json: schema: $ref: '#/components/schemas/GetTeamsForUserResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /v1/usersmanagement/listTeams: get: operationId: listTeams summary: List teams tags: - Teams description: 'Returns the teams in your tenant, with each team''s business unit and owner. Use it to look up team IDs, for example before you list the applications shared with a team. ADMIN and GLOBAL_VIEWER credentials see every team. Other credentials see only the teams they belong to. Teams are created and managed in the console. See [Teams](/docs/teams). **Access:** Scope: `team:list` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - name: businessUnit in: query required: false description: A business unit ID, to list only that unit's teams. Use the `businessUnitId` value from a team. Omit it to list teams in all business units. schema: type: string responses: '200': description: The teams visible to your credential. Member lists are not included; get a single team to see its members. content: application/json: schema: $ref: '#/components/schemas/ListTeamsResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: The business unit is not found or not visible to you. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/applications/har: post: operationId: registerApplicationFromHar summary: Register an application from a HAR file tags: - Applications description: 'Creates an application from a HAR (HTTP Archive) capture of real requests and responses, which APIsec converts to an OpenAPI spec. Use it when you have no spec but can record traffic with browser developer tools or a proxy. The file name must end in `.har`; a missing file or other extension returns 400, and a capture over the size limit returns 413. See [HAR](/docs/onboarding/har). **Access:** Scope: `app:create` · Roles: ADMIN, USER' requestBody: required: true content: multipart/form-data: schema: type: object required: - applicationName - origin - fileUpload properties: applicationName: type: string description: Display name of the application in the console. origin: type: string description: Free-form label for where the registration came from. Pipelines typically send `CI_CD`. fileUpload: type: string format: binary description: The HAR capture. The file name must end in `.har`. integrationDetails: type: string description: Optional. A JSON object of string key-value pairs, sent as a string, describing the integration the application came from. description: Multipart form with the application name and the HAR file. responses: '200': description: Application registered. content: application/json: schema: $ref: '#/components/schemas/RegisterApplicationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '413': description: The HAR file is larger than the accepted size. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/applications/burp: post: operationId: registerApplicationFromBurp summary: Register an application from a Burp Suite XML export tags: - Applications description: 'Creates an application from a Burp Suite XML export of captured HTTP traffic, which APIsec converts to an OpenAPI spec. Use it when you test the API with Burp Suite and have no spec. See [Burp XML](/docs/onboarding/burpxml). **Access:** Scope: `app:create` · Roles: ADMIN, USER' requestBody: required: true content: multipart/form-data: schema: type: object required: - applicationName - origin - fileUpload properties: applicationName: type: string description: Display name of the application in the console. origin: type: string description: Free-form label for where the registration came from. Pipelines typically send `CI_CD`. fileUpload: type: string format: binary description: Burp Suite XML export containing the captured requests and responses. integrationDetails: type: string description: Optional. A JSON object of string key-value pairs, sent as a string, describing the integration the application came from. description: Multipart form with the application name and the Burp XML export. responses: '200': description: Application registered. content: application/json: schema: $ref: '#/components/schemas/RegisterApplicationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /v1/applications/mitmproxy: post: operationId: registerApplicationFromMitmproxy summary: Register an application from a mitmproxy flow file tags: - Applications description: 'Creates an application from a mitmproxy flow dump (`.mitm`), which APIsec converts to an OpenAPI spec. Use it when you capture the API''s traffic with mitmproxy and have no spec. Upload the flow file exactly as mitmproxy wrote it. See [Mitmproxy](/docs/onboarding/mitmproxy). **Access:** Scope: `app:create` · Roles: ADMIN, USER' requestBody: required: true content: multipart/form-data: schema: type: object required: - applicationName - origin - fileUpload properties: applicationName: type: string description: Display name of the application in the console. origin: type: string description: Free-form label for where the registration came from. Pipelines typically send `CI_CD`. fileUpload: type: string format: binary description: mitmproxy flow file (`.mitm`), unmodified. integrationDetails: type: string description: Optional. A JSON object of string key-value pairs, sent as a string, describing the integration the application came from. description: Multipart form with the application name and the mitmproxy flow file. responses: '200': description: Application registered. content: application/json: schema: $ref: '#/components/schemas/RegisterApplicationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /v1/applications/{applicationId}/rename: put: operationId: renameApplication summary: Rename an application tags: - Applications description: 'Changes an application''s display name. The `applicationId` and everything under the application stay the same. You need Edit permission on the application; users with View permission on a shared application cannot rename it. See [Manage applications and environments](/docs/manage-applications-and-environments). **Access:** Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RenameApplicationRequest' description: The new display name. responses: '200': description: Application renamed. content: application/json: schema: $ref: '#/components/schemas/RenameApplicationResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/link: put: operationId: linkApplicationGatewayApi summary: Link or unlink an API gateway tags: - Applications description: 'Connects an application to an API in a gateway or API management platform, or removes that connection. A linked application can reload its spec from the gateway instead of from a file or URL. Set `action` to `LINK` or `UNLINK`, and supply the details object for your platform. See [Reload Spec](/docs/auto-reloadspec). **Access:** Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ApiGatewayDetails' description: The action and the gateway details for the platform. responses: '200': description: The gateway connection was linked or unlinked. content: application/json: schema: $ref: '#/components/schemas/MessageResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/downloadSpecFile: get: operationId: downloadApplicationSpecFile summary: Download an application's spec tags: - Applications description: 'Downloads the OpenAPI spec APIsec currently holds for the application, as a file attachment. For an application registered from a Postman collection or captured traffic, this is the OpenAPI spec APIsec converted it to. After one or more spec reloads, you get the latest version. The file name is the application name plus the spec''s original extension. **Access:** Scope: `app:get` · Roles: ADMIN, USER' parameters: - $ref: '#/components/parameters/ApplicationId' responses: '200': description: The spec file, as an attachment. content: application/octet-stream: schema: type: string format: binary '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/reload-diff/latest: get: operationId: getLatestInstanceReloadDiff summary: Get the latest reload diff tags: - Environments description: 'Shows what the most recent spec reload changed in an environment: how many endpoints were added and removed, whether the reload succeeded, and when it finished. Call it after Reload an environment''s spec to confirm the reload applied as expected; compare `timestamp` with the time you started the reload to know the result is yours. The added and removed endpoint lists are included only when `manifestAvailable` is `true`. A 404 means no reload has been recorded for the environment. See [View the reload diff](/docs/auto-reloadspec). **Access:** Scope: `app:get` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' responses: '200': description: The latest reload diff for the environment. content: application/json: schema: $ref: '#/components/schemas/GetReloadDiffResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/issuetracker: get: operationId: getInstanceIssueTracker summary: Get an environment's issue tracker tags: - Issue Tracker description: 'Returns the issue tracker attached to an environment: which connection it uses, the target project and whether automatic ticket sync is on. Call it to check an environment''s ticketing setup before you rely on tickets in a pipeline. If no issue tracker is attached, the response is `200` with a plain message saying the configuration is not set, instead of a configuration object. **Access:** Scope: `app:get` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' responses: '200': description: The attached issue tracker, or a message saying none is attached. content: application/json: schema: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' put: operationId: updateInstanceIssueTracker summary: Update an environment's issue tracker tags: - Issue Tracker description: 'Changes the issue tracker settings on an environment, such as the connection, the target project or automatic ticket sync. Use it to point an environment at a different project, or to turn automatic tickets on or off without detaching the tracker. Send `connectionId`, `projectKey` and `syncIssues` together, because they are saved as one set. An issue tracker must already be attached to the environment. **Access:** Scope: `issuetracker:add` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InstanceIssueTrackerConfigPayloadRequest' description: The full set of issue tracker settings for the environment. responses: '200': description: The issue tracker settings are updated. The response echoes the saved configuration. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' post: operationId: createInstanceIssueTracker summary: Attach an issue tracker to an environment tags: - Issue Tracker description: 'Attaches an existing issue tracker connection to an environment so its detections can become tickets. This is the **Activate Connection** step on an application''s **Issue Tracker** page in the console. Create the connection first in the console under **Integrations** › **Issue Tracker**, then attach it to each environment that should raise tickets. Set `syncIssues` to `true` to create tickets automatically after each scan. To change the attached tracker later, update it instead of attaching a second one. See [Integrate Jira issue tracking](/docs/integrations/Issuetrackers/jira). **Access:** Scope: `issuetracker:add` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InstanceIssueTrackerConfigPayloadRequest' description: The connection to attach, its target project and whether to sync tickets automatically. responses: '200': description: The issue tracker is attached. The response echoes the saved configuration. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' delete: operationId: deleteInstanceIssueTracker summary: Detach the issue tracker from an environment tags: - Issue Tracker description: 'Removes the issue tracker from an environment, so the environment stops raising tickets. This removes only the environment''s link to the tracker. The connection itself stays on the console''s **Integrations** page, available to other environments. To delete the connection, use the console. **Access:** Scope: `issuetracker:remove` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' responses: '200': description: The issue tracker is detached from the environment. content: application/json: schema: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/detections/{detectionId}/create-ticket: post: operationId: createDetectionTicket summary: Create a ticket for a detection tags: - Detections description: 'Raises a ticket for one detection in the issue tracker attached to its environment. This is the **Create a ticket** action on the console''s detection detail view. Use it when automatic ticket sync is off, or to ticket a detection on demand. The ticket carries the detection''s endpoint, severity, evidence, remediation and, for ServiceNow, the environment''s metadata tags. Attach an issue tracker to the environment first. If none is attached, no ticket is created and the response is an empty list. If the issue tracker rejects the request, the response carries the tracker''s status code and message. See [Create a ticket from a finding](/docs/vulnerability-details/create-ticket). **Access:** Scope: `detections:update` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: detectionId in: path required: true schema: type: string description: The detection's ID, from `detectionId` in the list of detections. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateDetection' description: Send `comments` to add a note to the ticket. The other fields are not needed. responses: '200': description: The ticket is created and linked to the detection. Get the detection to read its `ticketDetails`. content: application/json: schema: type: array items: type: string '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /v1/applications/{applicationId}/instances/{instanceId}/threat-detection/create-ticket: post: operationId: createThreatDetectionTicket summary: Create tickets for several detections tags: - Detections description: 'Raises tickets for several detections in one request, in the background. The console uses it from the [Threat Detection](/docs/threat-detection) view, where one weakness affects many endpoints. List the detections in `detectionIds`. Leave `status` unset to create tickets. Set `status` to `FALSE_POSITIVE` to mark the listed detections as false positives and update their existing tickets. The call returns as soon as the work is queued, with the plain-text body `Creating tickets in background.` It returns no ticket IDs. To check the result, get each detection and read its `ticketDetails`. Attach an issue tracker to the environment first. **Access:** Scope: `detections:update` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateDetection' description: '`detectionIds` lists the detections to ticket. Add `comments` to include a note on each ticket.' responses: '200': description: The request is accepted and the tickets are being created in the background. The body is plain text, not JSON. content: text/plain: schema: type: string '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /v1/applications/{applicationId}/instances/{instanceId}/reload-spec/raml: patch: operationId: updateReloadSpecRamlFlag summary: Set the MuleSoft RAML reload option tags: - Environments description: 'Chooses whether reloads of a MuleSoft-linked application use the API''s RAML definition. It applies only to applications onboarded from MuleSoft. Send the setting as the `raml` query parameter; the request has no body. See [MuleSoft](/docs/integrations/mulesoft). **Access:** Scope: `app:create` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: raml in: query required: true schema: type: boolean description: '`true` to reload from the RAML definition, `false` otherwise.' responses: '200': description: The option was saved. The body is empty. content: application/json: schema: type: object nullable: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /v1/applications/{applicationId}/instances/{instanceId}/delete-endpoints: post: operationId: deleteInstanceEndpoints summary: Delete endpoints from an environment tags: - Endpoints description: 'Removes endpoints from an environment so that APIsec no longer tests them. Use it to drop endpoints your API no longer serves. The body is a JSON array of endpoint `id` values from List an environment''s endpoints; an empty array returns 400. To remove every endpoint that a new spec no longer contains, reload the spec with `deleteEndpoints` instead. See [Manage endpoints](/docs/manage-endpoints). **Access:** Scope: `app:create` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: application/json: schema: type: array items: type: string description: Endpoint ids to delete. description: A JSON array of endpoint IDs to delete. Must not be empty. responses: '200': description: The endpoints were deleted. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/reload-spec/schedule: get: operationId: getAutoReloadSpecSchedule summary: Get an environment's auto-reload schedule tags: - Environments description: 'Returns the schedule on which APIsec reloads an environment''s spec from its linked API gateway, with the next run time. Use it to confirm that a gateway-linked environment stays in step with the gateway. Auto-reload is available for applications linked to AWS API Gateway, Azure APIM, MuleSoft, SwaggerHub or Postman. A 404 means no schedule is configured, or the application is not found or not shared with you. See [Auto-Reload Spec with API Gateway](/docs/auto-reloadspec). **Access:** Scope: `app:get` · Any role · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' responses: '200': description: The auto-reload schedule. content: application/json: schema: $ref: '#/components/schemas/AutoReloadSpecSchedule' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/reload-sdl: post: operationId: reloadInstanceSdl summary: Reload an environment's GraphQL schema tags: - Environments description: 'Replaces the GraphQL schema behind an environment with a new SDL or introspection file, so its queries and mutations match your current API. This is the GraphQL counterpart of Reload an environment''s spec. If you omit the options, APIsec keeps endpoints missing from the new schema and keeps your endpoint settings and parameter values. Set `deleteEndpoints`, `overwriteEndpointConfig` or `overwriteVal` to `true` to remove or replace them. **Access:** Scope: `app:create` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: multipart/form-data: schema: type: object required: - fileUpload properties: fileUpload: type: string format: binary description: The GraphQL SDL or introspection result, as UTF-8 text. deleteEndpoints: type: boolean description: '`true` removes operations that are not in the new schema. Defaults to `false`.' overwriteEndpointConfig: type: boolean description: '`true` replaces custom endpoint settings with the new schema''s. Defaults to `false`, which keeps them.' overwriteVal: type: boolean description: '`true` replaces parameter values you set with the new schema''s. Defaults to `false`, which keeps them.' description: Multipart form with the new schema file and the reload options. responses: '200': description: The schema was reloaded. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/tags: get: operationId: listMetadataTags summary: List metadata tag fields tags: - Metadata Tags description: 'Lists every metadata tag field defined in your tenant, with its values and the number of environments each field is assigned to. Use it to find the `tagId` and `optionId` values you need to assign tags. This call is for administrators; any user can see the tags assigned to environments they can access in List applications and Get an application. **Access:** Role: ADMIN' responses: '200': description: The tenant's metadata tag fields. content: application/json: schema: $ref: '#/components/schemas/MetadataTagListResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' post: operationId: createMetadataTag summary: Create a metadata tag field tags: - Metadata Tags description: 'Defines a new tenant-wide metadata tag field with a label and its list of allowed values (options), from 1 to 50. Define a field once and reuse it across applications, rather than creating duplicates. On success the call returns 201 with the new field, including the `optionId` of each value. Assign values to environments with Assign or clear metadata tag values. **Access:** Role: ADMIN' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMetadataTagRequest' description: The field label and its options, in display order. responses: '201': description: The new field, with generated `tagId` and `optionId` values. content: application/json: schema: $ref: '#/components/schemas/MetadataTagRecord' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /v1/applications/tags/{tagId}: put: operationId: updateMetadataTag summary: Replace a metadata tag field tags: - Metadata Tags description: 'Replaces a field''s label and its full list of options; the `tagId` does not change. To keep an existing option, include it with its `optionId`. An existing option you leave out is deleted, and it is removed from every environment it was assigned to. Options without an `optionId` are added as new. **Access:** Role: ADMIN' parameters: - name: tagId in: path required: true schema: type: string description: ID of the metadata tag field, from List metadata tag fields. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateMetadataTagRequest' description: The new label and the complete list of options. responses: '200': description: The updated field. content: application/json: schema: $ref: '#/components/schemas/MetadataTagRecord' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' delete: operationId: deleteMetadataTag summary: Delete a metadata tag field tags: - Metadata Tags description: 'Deletes a metadata tag field. You can delete a field only when no environment has any of its values assigned (`instanceCount` is 0). Clear its values from those environments first with Assign or clear metadata tag values; List environments with a metadata tag field shows which ones they are. **Access:** Role: ADMIN' parameters: - name: tagId in: path required: true schema: type: string description: ID of the metadata tag field to delete. responses: '200': description: The field was deleted. content: application/json: schema: $ref: '#/components/schemas/MetadataTagDeleteAck' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: The field is still assigned to one or more environments. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/applications/tags/{tagId}/instances: get: operationId: listMetadataTagInstances summary: List environments with a metadata tag field tags: - Metadata Tags description: 'Lists every environment that has at least one value of this field assigned, with the `optionId` values it carries. Use it to audit a field''s use or to find the environments to clear before you delete it. Results are paginated: pass the `nextToken` from each response to get the next page. **Access:** Role: ADMIN' parameters: - name: tagId in: path required: true schema: type: string description: ID of the metadata tag field. - name: pageSize in: query required: false schema: type: integer description: Maximum number of environments to return on one page. - $ref: '#/components/parameters/NextToken' responses: '200': description: One page of instance assignments. content: application/json: schema: $ref: '#/components/schemas/MetadataTagInstancesResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/tags/values: post: operationId: updateInstanceMetadataTagValues summary: Assign or clear metadata tag values tags: - Metadata Tags description: 'Sets or clears metadata tag values on many environments in one call. `targets` lists the environments; `values` maps each `tagId` to the `optionId` values to assign, and a null or empty list clears that field. Fields you leave out of `values` are not changed, and one call can set up to 20 fields. Every reference is checked first, so an unknown environment, field or option returns 400 and changes nothing. After that, each environment is updated on its own, so the 200 response lists both `updatedTargets` and `failedTargets` — check `failedTargets` before you assume every environment was updated. **Access:** Scope: `app:create` · Roles: ADMIN, USER' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateInstanceMetadataTagValuesRequest' description: The environments to update and the values to set or clear per field. responses: '200': description: The outcome per environment. Some environments can fail while others succeed. content: application/json: schema: $ref: '#/components/schemas/UpdateInstanceMetadataTagValuesResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /v1/applications/tags/values/{applicationId}/{instanceId}: get: operationId: getInstanceMetadataTagValues summary: Get an environment's metadata tag values tags: - Metadata Tags description: 'Returns the metadata tag values assigned to one environment, with field and value labels. A field with no value assigned to this environment is left out of `values`. **Access:** Scope: `app:get` · Roles: ADMIN, USER, VIEWER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' responses: '200': description: The instance's assigned metadata tag values. content: application/json: schema: $ref: '#/components/schemas/InstanceMetadataTagsResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/usersmanagement/oauth/token: post: operationId: issueOAuthToken summary: Get an access token from OAuth client credentials tags: - Authentication security: [] description: 'Exchanges an OAuth client ID and secret for a short-lived bearer access token. Call this at the start of each pipeline run, then send the token as `Authorization: Bearer ` on every other call. The only supported grant is `client_credentials`. Send the request form-encoded, with the client ID and secret either in the body or as HTTP Basic credentials in the `Authorization` header. Client IDs start with `ac_` and secrets with `acs_`. Tokens last for the lifetime configured on the client: 3600 seconds by default, 86400 seconds at most. Revoking the client invalidates every token already issued from it. A Personal Access Token is already a bearer token and needs no exchange, so this endpoint does not accept one. See [API Credentials](/docs/api-token). **Access:** No API credential needed. Authenticate with your OAuth client ID and secret.' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - grant_type properties: grant_type: type: string enum: - client_credentials description: Always `client_credentials`. client_id: type: string description: Omit when using HTTP Basic. client_secret: type: string description: Omit when using HTTP Basic. description: Form-encoded `grant_type=client_credentials`, plus `client_id` and `client_secret` unless you send them as HTTP Basic credentials. responses: '200': description: Token issued. `expires_in` is the token's lifetime in seconds; request a new token before it elapses. content: application/json: schema: type: object properties: access_token: type: string token_type: type: string enum: - Bearer expires_in: type: integer description: Lifetime in seconds. example: access_token: eyJhbGciOi... token_type: Bearer expires_in: 3600 '400': description: The grant type is not `client_credentials`, or the request is malformed. content: application/json: schema: type: object properties: error: type: string error_description: type: string '401': description: The client ID is unknown or revoked, or the secret does not match. content: application/json: schema: type: object properties: error: type: string error_description: type: string /v1/applications/oas: post: operationId: registerOasApplication summary: Register an application from an OpenAPI spec tags: - Applications description: 'Creates an application from an OpenAPI (Swagger) spec that you upload as a file or that APIsec fetches from a URL. This is the usual first call when you onboard an API from a script or pipeline. Send exactly one of `fileUpload` or `oasUrl`; sending neither returns 400. To make the call idempotent, send an `externalId`: if an application with that external ID (and `qualifier`) already exists, the call returns it with `created` set to `false` instead of creating another one. To push a new version of the spec to an existing application, use Reload an environment''s spec. See [Onboard an API with an OpenAPI spec](/docs/create-application). **Access:** Scope: `app:create` · Roles: ADMIN, USER' requestBody: required: true content: multipart/form-data: schema: type: object required: - applicationName - origin properties: applicationName: type: string description: Display name of the application in the console. origin: type: string description: Free-form label for where the registration came from. Pipelines typically send `CI_CD`. fileUpload: type: string format: binary description: The OpenAPI spec file (`.json` or `.yaml`). Omit when you send `oasUrl`. oasUrl: type: string description: URL that returns the OpenAPI spec without authentication. Omit when you upload a file. integrationDetails: type: string description: Optional. A JSON object of string key-value pairs, sent as a string, describing the integration the application came from. Omit it for a direct upload. externalId: type: string description: Optional. Your own stable identifier for this application, such as a repository ID. Registering again with the same value returns the existing application. qualifier: type: string description: Optional. Distinguishes several applications that share one `externalId`, for example one per service in a monorepo. description: Multipart form with the application name, the spec (file or URL) and optional external ID. responses: '200': description: The registered application. `created` is `false` when an application with the same `externalId` and `qualifier` already existed. content: application/json: schema: $ref: '#/components/schemas/RegisterApplicationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /v1/applications/postman: post: operationId: registerPostmanApplication summary: Register an application from a Postman collection tags: - Applications description: 'Creates an application from a Postman collection, which APIsec converts to an OpenAPI spec. Upload the exported collection file, or send `collectionId` and `apiKey` to have APIsec fetch the collection from your Postman workspace. Use this when your API is documented in Postman rather than in an OpenAPI spec. See [Postman](/docs/integrations/postman). **Access:** Scope: `app:create` · Roles: ADMIN, USER' requestBody: required: true content: multipart/form-data: schema: type: object required: - applicationName - origin properties: applicationName: type: string description: Display name of the application in the console. origin: type: string description: Free-form label for where the registration came from. Pipelines typically send `CI_CD`. fileUpload: type: string format: binary description: Exported Postman collection file. Omit when you send `collectionId` and `apiKey`. collectionId: type: string description: ID of the collection in Postman. Requires `apiKey`. apiKey: type: string description: Postman API key with read access to the collection. Required with `collectionId`. integrationDetails: type: string description: Optional. A JSON object of string key-value pairs, sent as a string, describing the integration the application came from. description: Multipart form with the application name and either a collection file or a Postman collection ID and API key. responses: '200': description: Application registered. content: application/json: schema: $ref: '#/components/schemas/RegisterApplicationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /v1/applications/graphql: post: operationId: registerGraphqlApplication summary: Register an application from a GraphQL schema tags: - Applications description: 'Creates an application from a GraphQL schema, uploaded as an SDL file or discovered by introspection against `introspectionUrl`. Use this to onboard a GraphQL API. If the response''s `hostUrls` is empty, add an environment with the GraphQL endpoint URL using Add environments. See [Onboard a GraphQL API](/docs/graphql). **Access:** Scope: `app:create` · Roles: ADMIN, USER' requestBody: required: true content: multipart/form-data: schema: type: object required: - applicationName - origin properties: applicationName: type: string description: Display name of the application in the console. origin: type: string description: Free-form label for where the registration came from. Pipelines typically send `CI_CD`. fileUpload: type: string format: binary description: GraphQL schema (SDL) file. Omit when you send `introspectionUrl`. introspectionUrl: type: string description: GraphQL endpoint URL that APIsec queries by introspection to read the schema. Omit when you upload a file. description: Multipart form with the application name and either an SDL file or an introspection URL. responses: '200': description: Application registered. content: application/json: schema: $ref: '#/components/schemas/RegisterApplicationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /v1/applications: get: operationId: listApplications summary: List applications tags: - Applications description: 'Lists the applications you can access, each with its environments and their latest scan statistics. Use it to find `applicationId` and `instanceId` values, or to report on scan coverage across your portfolio. Results are paginated: pass the `nextToken` from each response to get the next page, until `nextToken` is empty. To list the applications shared with one team, send `memberId` with `memberType=TEAM`; sending only one of the two returns 400. **Access:** Scope: `app:get` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - $ref: '#/components/parameters/NextToken' - name: excludeDetectionsWithStatus in: query required: false description: Detection statuses to leave out of the counts, for example `DISMISSED`. Repeat the parameter for several statuses. schema: type: array items: type: string - name: memberId in: query required: false description: A team ID. Returns only applications shared with that team. Requires `memberType`. schema: type: string - name: memberType in: query required: false description: Must be `TEAM`. Requires `memberId`. schema: $ref: '#/components/schemas/MemberType' - name: include in: query required: false description: 'Comma-separated extras: `scores` adds each environment''s App Model completion; `teams` adds the teams each application is shared with.' schema: type: string responses: '200': description: A page of applications. content: application/json: schema: $ref: '#/components/schemas/GetApplicationsResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /v1/applications/{applicationId}: get: operationId: getApplication summary: Get an application tags: - Applications description: 'Returns one application, its environments, and your access to it. Use it to read the `instanceId` of each environment before you configure authentication or start a scan. This response does not include scan statistics; use List applications for those. A 404 means the application does not exist or is not shared with you — the two cases look the same. For a USER credential, an application shared with you through a team needs the `team:get` scope as well. **Access:** Scope: `app:get` · Any role' parameters: - $ref: '#/components/parameters/ApplicationId' - name: include in: query required: false description: Comma-separated extras. `scores` adds each environment's App Model completion. schema: type: string responses: '200': description: The application. content: application/json: schema: $ref: '#/components/schemas/ApplicationRecord' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' delete: operationId: deleteApplication summary: Delete an application tags: - Applications description: 'Deletes an application together with its environments and everything configured or recorded under them. Use it to remove an API you no longer test. After deletion you can register a new application with the same external ID. See [Delete an application](/docs/delete-app). **Access:** Scope: `app:delete` · Any role' parameters: - $ref: '#/components/parameters/ApplicationId' responses: '200': description: The application was deleted. content: application/json: schema: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/membership: post: operationId: shareApplication summary: Share an application with a team tags: - Applications description: 'Gives one or more teams access to an application, with View or Edit permission. Team members can then work with the application according to that permission. Send either a single `memberId` with `memberType`, or a `members` array; sending neither returns 400. Get team IDs from the Teams endpoints. See [Manage applications and environments](/docs/manage-applications-and-environments). **Access:** Scope: `app:manage:access` · Roles: ADMIN, USER' parameters: - $ref: '#/components/parameters/ApplicationId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ShareApplicationRequest' example: memberId: team-123 memberType: TEAM permission: Edit description: The team or teams to grant access to, and the permission for each. responses: '200': description: Access granted. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' delete: operationId: unshareApplication summary: Remove a team's access to an application tags: - Applications description: 'Revokes a team''s access to an application. Members of that team lose access unless it is also shared with them another way. See [Manage applications and environments](/docs/manage-applications-and-environments). **Access:** Scope: `app:manage:access` · Roles: ADMIN, USER' parameters: - $ref: '#/components/parameters/ApplicationId' requestBody: required: true content: application/json: schema: type: object required: - memberId - memberType properties: memberId: type: string description: ID of the team to remove from the application. memberType: $ref: '#/components/schemas/MemberType' description: The team to remove. `memberType` must be `TEAM`. responses: '200': description: Access revoked. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/batch: post: operationId: addInstances summary: Add environments to an application tags: - Environments description: 'Adds one or more environments to an application, each pointing at a host URL. Use it when the spec has no usable server URL, or to test the same API in another deployment such as staging. The body is a JSON array with one object per environment. APIsec then checks whether each new environment is reachable. The response does not include the new `instanceId` values; read them from Get an application. **Access:** Scope: `app:create` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' requestBody: required: true content: application/json: schema: type: array items: type: object properties: hostUrl: type: string description: Base URL of the deployment to test, including the scheme, for example `https://staging.example.com`. instanceName: type: string description: Optional display name for the environment, for example `staging`. environmentVar: type: string description: Optional. A Postman environment export, as a JSON string, for applications registered from a Postman collection. description: A JSON array of environments to add, each with `hostUrl` and an optional `instanceName`. responses: '200': description: The environments were added. The body does not list their IDs. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/updateInstanceHostUrl: put: operationId: updateInstanceHostUrl summary: Update an environment's host URL or name tags: - Environments description: 'Changes the host URL an environment points at, and optionally its display name. Use it when a deployment moves, for example when a pipeline creates a fresh test host on each run. The environment keeps its ID, authentication and endpoints. See [Manage applications and environments](/docs/manage-applications-and-environments). **Access:** Scope: `app:create` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: application/json: schema: type: object properties: hostUrl: type: string description: New base URL of the deployment, including the scheme. instanceName: type: string description: Optional new display name for the environment. description: The new `hostUrl` and, optionally, a new `instanceName`. responses: '200': description: The environment was updated. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/reload-spec: post: operationId: reloadInstanceSpec summary: Reload an environment's spec tags: - Environments description: 'Replaces the spec behind an environment with a new version, so its endpoints match your current API. Call it from a pipeline after the API changes, before you scan. Send the new spec as a file, a URL, or a Postman collection ID with an API key. If you omit them, `deleteEndpoints`, `overwriteEndpointConfig` and `overwriteVal` each default to `true` — endpoints missing from the new spec are removed and your endpoint settings and parameter values are replaced. Set the overwrite flags to `false` to keep your configuration, matching the console''s **Retain** options. APIsec applies the reload after the call returns; check the outcome with Get the latest reload diff. **Access:** Scope: `app:create` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: multipart/form-data: schema: type: object properties: fileUpload: type: string format: binary description: The new spec file. Omit when you send `oasUrl` or `collectionId`. oasUrl: type: string description: URL that returns the new spec without authentication. collectionId: type: string description: Postman collection ID to reload from. Requires `apiKey`. apiKey: type: string description: Postman API key with read access to the collection. Required with `collectionId`. overwriteVal: type: string description: '`true` (default) replaces parameter values you set at the environment or endpoint level with values from the new spec. `false` keeps them — the console''s **Retain Existing Parameter Values**.' overwriteEndpointConfig: type: string description: '`true` (default) replaces custom endpoint settings such as authorization, parameters, headers, data types and example values. `false` keeps them — the console''s **Retain Existing Endpoint Configurations**.' deleteEndpoints: type: string description: '`true` (default) removes endpoints that are not in the new spec — the console''s **Remove Missing Endpoints**. `false` keeps them.' raml: type: string description: 'For applications linked to MuleSoft only: `true` reloads from the API''s RAML definition.' environmentFile: type: string format: binary description: Optional Postman environment export (JSON with a `values` array) used to resolve variables in a collection. description: Multipart form with the new spec source and the reload options. responses: '200': description: The reload was accepted. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/rbac-mapping: post: operationId: uploadRbacMapping summary: Upload an RBAC map tags: - Environments description: 'Uploads an RBAC map for an environment — which roles should be able to reach which endpoints — for authorization (RBAC) testing. Start from the CSV the console produces with **Download RBAC Map**, edit it, and upload it here. The roles must already exist as authentications on the environment. The response reports the access checks for each role. See [Configure RBAC for application roles](/docs/rbac/rbac-details). **Access:** Scope: `app:create` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: multipart/form-data: schema: type: object required: - fileUpload properties: fileUpload: type: string format: binary description: The RBAC map, in the CSV format of the console's **Download RBAC Map**. description: Multipart form with the RBAC map file. responses: '200': description: The access-check results for each role in the uploaded map. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/endpoints: get: operationId: listInstanceEndpoints summary: List an environment's endpoints tags: - Endpoints description: 'Lists the endpoints APIsec tests in an environment, grouped by resource, with each endpoint''s method, path and sensitivity. Use it to review coverage, or to get the endpoint `id` values that other calls take, such as Delete endpoints. Add `include=metadata` for summary counts, and `slim=true` for a smaller response. See [Manage endpoints](/docs/manage-endpoints). **Access:** Scope: `app:get` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: include in: query required: false description: Comma-separated extras. `metadata` adds counts of endpoints, endpoints that require authentication, and sensitive endpoints. schema: type: string - name: slim in: query required: false description: '`true` returns a reduced representation of each endpoint. Defaults to `false`.' schema: type: boolean default: false responses: '200': description: The environment's endpoints, grouped in `endpointGroups`. content: application/json: schema: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/add-endpoints: post: operationId: addInstanceEndpoints summary: Add endpoints to an environment tags: - Endpoints description: 'Adds endpoints to an environment by hand, without reloading its spec. Use it for an endpoint the spec does not describe. The body is a JSON array with one object per endpoint, giving its `method`, its `endpoint` path, and an optional example `payload`. Added endpoints are tested in later scans. See [Manage endpoints](/docs/manage-endpoints). **Access:** Scope: `app:create` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: application/json: schema: type: array items: type: object additionalProperties: true description: A JSON array of endpoints, each with `method`, `endpoint` (the path) and an optional `payload`. responses: '200': description: The endpoints were added. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/headers: get: operationId: getInstanceHeaders summary: Get an environment's headers tags: - Environments description: 'Returns the environment-level headers APIsec sends with requests to this environment — non-authentication headers such as a routing key or static cookie. Confidential header values come back masked. Read them before you call Replace an environment''s headers, because that call replaces the whole set. See [Manage Headers](/docs/manage-headers). **Access:** Scope: `app:get` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' responses: '200': description: The environment's headers, in `data`. Confidential values are masked. content: application/json: schema: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' put: operationId: updateInstanceHeaders summary: Replace an environment's headers tags: - Environments description: 'Sets the environment-level headers APIsec sends with requests to this environment. Use it for headers every request needs that are not part of authentication, such as a header a load balancer requires. The call replaces the full set: any header you omit is removed. To keep a confidential header unchanged, send it with the masked value you received from Get an environment''s headers. Set `enabledForReachability` on a header that must also be sent on the reachability check. See [Manage Headers](/docs/manage-headers). **Access:** Scope: `app:create` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: application/json: schema: type: object required: - eventData properties: eventData: type: object required: - headers properties: headers: type: array items: type: object additionalProperties: true description: Wrapper object. Put the complete list of headers in `eventData.headers`; any header you leave out is removed. description: The complete list of headers for the environment, in `eventData.headers`. responses: '200': description: The headers were replaced. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/auths: get: operationId: listInstanceAuths summary: List authentication configurations tags: - Authentication Configurations description: 'Returns the authentication configurations on an environment, the same list the console shows under **Credentials**. Call it to find the `authId` to test with `testCreds` or to pass as `scanWithAuthId` when you start a scan. Secret values are masked. A credential linked from a [global credential](/docs/global-credentials) appears with its name and `globalAuthId` only; its scheme and secrets belong to the global credential. **Access:** Scope: `app:get` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' responses: '200': description: The environment's authentication configurations, with secret values masked. content: application/json: schema: type: object properties: instanceCredentials: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' post: operationId: createInstanceAuth summary: Create an authentication configuration tags: - Authentication Configurations description: 'Creates an authentication configuration that tells APIsec how to sign in to this environment''s API while scanning. Create one before you run an authenticated scan; the response is the new `authId` as a JSON string. `authScheme.type` selects the authentication type. Use only the values listed for it. A `200` means the configuration was saved, not that it signs in successfully, so test it with `testCreds` before you rely on it. Names must be unique within the environment. See [Configure authentication](/docs/setting-up-auth). **Access:** Scope: `app:create` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AuthenticationConfig' example: name: bearer-user-a role: '' isDefault: true authScheme: type: HTTP tokenTTL: 30 placement: in: header key: Authorization contentType: in: Header key: application/json responseKey: in: Header key: token additionalHeaders: in: Header key: '' additionalBodyParameters: in: Body key: '' authProviderList: - scheme: bearerToken authUrl: https://api.example.com/auth/login discoveryUrl: '' tokenUrl: '' credentials: username: providerKey: email credentialValue: scanner@example.com password: providerKey: password credentialValue: REDACTED description: The authentication configuration. `name` and `authScheme` are required; `credentials` depends on the type. responses: '200': description: The new configuration's `authId`, as a JSON string. content: application/json: schema: type: string '400': description: '`tokenTTL` is below 5 minutes, the name is already used in this environment, or an HMAC configuration is incomplete.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/auths/{authId}: put: operationId: updateInstanceAuth summary: Update an authentication configuration tags: - Authentication Configurations description: 'Replaces an authentication configuration with the body you send. Call it when a credential rotates or a login endpoint changes. Send the complete configuration, including credential values; fields you omit are not kept from the previous version. The body and validation rules are the same as for creation. Run `testCreds` again afterwards to confirm the new values work. **Access:** Scope: `app:create` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: authId in: path required: true schema: type: string description: ID of the authentication configuration to replace, from `listInstanceAuths` or the create response. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AuthenticationConfig' description: The complete replacement configuration. responses: '200': description: The configuration's `authId`, as a JSON string. content: application/json: schema: type: string '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/testCreds: post: operationId: testInstanceCredentials summary: Test an authentication configuration tags: - Authentication Configurations description: 'Signs in to your API with an authentication configuration and calls one endpoint with the result, so you know the credential works before you scan. Read the `valid` field: `true` means the test passed. Pass `authId` to test a saved configuration, or send a configuration in the body to test it before you save it. The test runs from the APIsec cloud unless the environment uses a hosted agent. A host that is reachable only inside your network therefore needs a hosted agent; without one the call returns `400` with `Instance URL is not reachable.`, which describes reachability, not the credential. If the endpoint returns `403` for this identity, test against a different endpoint with `endpointId`. See [Configure authentication](/docs/setting-up-auth). **Access:** Scope: `app:get` · Roles: ADMIN, USER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: authId in: query required: false description: ID of a saved authentication configuration to test. Omit it when you send a configuration in the request body. schema: type: string - name: endpointId in: query required: false description: ID of the endpoint to call with the resolved credential. Omit it to let APIsec choose an endpoint. schema: type: string requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/AuthenticationConfig' description: Optional. An unsaved authentication configuration to test instead of a saved one. responses: '200': description: The test ran. Check `valid` for the result; the other fields show the sign-in request and the endpoint call. content: application/json: schema: $ref: '#/components/schemas/TestAuthenticationResponse' example: method: POST endpoint: https://api.example.com/auth/login responseStatusCode: 200 valid: true authResolvedUrl: https://api.example.com/auth/login authResolvedResponseStatusCode: 200 '400': description: '`Instance URL is not reachable.` means APIsec could not reach the environment''s host from where the test ran. `Invalid credentials.` means sign-in failed.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/scan: post: operationId: startScan summary: Start a scan tags: - Scans description: 'Starts a security scan of an environment and returns its `scanId`. This is the first step of a CI/CD gate: start the scan, poll `getScan` until it finishes, then read its detections. An empty body `{}` starts an unauthenticated scan of every endpoint, the same as choosing **None** as the credential in the console. Narrow the scope with `endpointIds` and `categories`, choose a saved credential with `scanWithAuthId`, or supply a one-off configuration in `inlineAuthentication`. Name a saved scan profile with `profileId` to reuse its scope; any field you also send in the body takes precedence over the profile''s value. `scanWithAgent` runs the scan on a specific hosted agent, which must be `ACTIVE`. Starting a scan does not check for one already running, so query `listScans` with `status=running` first if you want one scan at a time. **Access:** Scope: `scan:init` · Roles: ADMIN, USER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: application/json: schema: type: object properties: endpointIds: type: array items: type: string description: Endpoint IDs to scan, from the environment's endpoint list. Omit to scan every endpoint. categories: type: array items: type: string description: Security test categories to run. Omit to run every category. scanWithAuthId: type: string description: ID of a saved credential for this environment, from the list of authentication configurations. Omit for an unauthenticated scan. scanWithAgent: type: string description: ID of an `ACTIVE` hosted agent to run the scan on. Omit to use the environment's default hosted agent, if one is set. inlineAuthentication: $ref: '#/components/schemas/AuthenticationConfig' profileId: type: string description: ID of a saved scan profile whose scope to reuse. Fields you send in the body take precedence over the profile's values. example: endpointIds: [] categories: [] scanWithAuthId: a1b2c3d4 description: 'Scan scope. Every field is optional: `endpointIds`, `categories`, `scanWithAuthId` or `inlineAuthentication`, `scanWithAgent`, and `profileId`.' responses: '200': description: Scan started. The body carries the new `scanId`. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' /v1/applications/{applicationId}/instances/{instanceId}/scans: get: operationId: listScans summary: List scans for an environment tags: - Scans description: 'Returns the scans of an environment, newest first. Call it with `status=running` to check whether a scan is already in progress before you start one, or to find recent results. `status` is required. Its values are lowercase (`running`, `completed`, `failed`, `aborted`), while each scan''s `status` in the response is title case (`Processing`, `Complete`, `Failed`, `Aborted`). A running scan reports `Processing`. Every matching scan is returned in one response; `nextToken` is always null. **Access:** Scope: `scan:get` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: status in: query required: true description: Required. One or more of `running`, `completed`, `failed`, `aborted`, comma-separated, for example `running,completed`. schema: type: string example: running,completed responses: '200': description: The matching scans, newest first. content: application/json: schema: $ref: '#/components/schemas/GetScansResponse' example: scans: - scanId: s-9001 startTime: '2026-09-16T02:00:04Z' lastUpdateTime: '2026-09-16T02:41:55Z' status: Complete triggerSource: SCHEDULED executionSummary: totalTestsExecuted: 1420 totalTestsPassed: 1388 totalTestsFailed: 32 totalTestsSkipped: 0 newDetections: 4 detectionsResolved: 1 activeDetections: 19 nextToken: null '401': $ref: '#/components/responses/Unauthorized' '403': description: Your credential is not permitted to read scans. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/scans/{scanId}: get: operationId: getScan summary: Get a scan tags: - Scans description: 'Returns one scan: its `status`, `statusReason`, progress counters in `metadata`, and its detections grouped by endpoint under `vulnerabilities` and `issues`. Poll it after `startScan` until `status` is `Complete`, `Failed`, or `Aborted`; `Processing` means the scan is still running. Bound the loop with your own timeout. Poll every 30 to 60 seconds. `Complete` means the scan finished, not that every endpoint passed. To gate a build, read every page of `vulnerabilities` by following `nextToken`, and count the detections whose `testResult.cvssQualifier` is Critical or High. See [CI/CD integration](/docs/ci-cd-integration). **Access:** Scope: `scan:get` · Any role' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: scanId in: path required: true schema: type: string description: The scan's ID, from the `startScan` response or `listScans`. - $ref: '#/components/parameters/NextToken' - name: limit in: query required: false description: Page size for the detections in the response. Defaults to 25. `0` returns all of them on one page. schema: type: integer responses: '200': description: The scan, with one page of detections. content: application/json: schema: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/detections: get: operationId: listDetections summary: List detections for an environment tags: - Detections description: 'Returns the current detections for an environment, as shown on the console''s **Vulnerabilities** tab. Call it after a scan finishes to count open detections and gate a build, or to export results. Each detection shows its latest state across all scans, not only the most recent scan. The response groups detections by security test. Each entry in `detections` names a test category and test, and lists its detections under `data.vulnerabilities`. Tests with no detections still appear, with an empty list. For a build gate, count detections with `status` `ACTIVE` and `isVulnerability` `true`. Detections with `isVulnerability` `false` are informational. **Access:** Scope: `scan:get` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: include in: query required: false schema: type: string description: Comma-separated extras to add to the response. `metadata` adds a `metadata` object with totals for the environment. With `slim=true`, `remediation`, `description` and `cwes` add those text fields back to each detection. - name: excludeDetectionsWithStatus in: query required: false description: Detection statuses to leave out, for example `DISMISSED`. Repeat the parameter for several statuses. The console's default view leaves out `DISMISSED`, so pass it to match what the console shows. schema: type: array items: type: string - name: slim in: query required: false schema: type: boolean description: Set to `true` for a smaller response that leaves out the long per-detection text (test evidence and comments). Recommended for environments with many detections and for CI/CD use. Use `include` to add specific text fields back. responses: '200': description: The environment's detections, grouped by security test. content: application/json: schema: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/detections/{detectionId}: get: operationId: getDetection summary: Get a detection tags: - Detections description: 'Returns one detection with its full detail: endpoint, test category, CVSS score and severity, status, the evidence that triggered it, remediation guidance and request logs. It matches the detail view you open from a row on the console''s **Vulnerabilities** tab. Use it to show evidence to a developer, or to read a detection''s ticket and triage details after you update it. Get `detectionId` from the list of detections for the environment. **Access:** Scope: `scan:get` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: detectionId in: path required: true schema: type: string description: The detection's ID, from `detectionId` in the list of detections. responses: '200': description: The detection. Triage fields such as `riskAcceptedEndDate`, `riskAcceptedBy` and `comments` are present once the detection has been triaged, and `ticketDetails` once a ticket exists. content: application/json: schema: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/detections/{detectionId}/update: put: operationId: updateDetection summary: Triage a detection tags: - Detections description: 'Marks a detection as False Positive or Risk Accepted, or overrides its CVSS score. These are the **Mark as False Positive** and **I accept the risk** actions on the console''s detection detail view. Set `status` to `FALSE_POSITIVE` or `RISK_ACCEPTED` and give your reason in `comments`. Any other `status` returns `400`. To change the CVSS score instead, set `updateCvss` to `true` and send the new `cvssScore`. If the detection already has a ticket, APIsec updates the ticket first. If the issue tracker rejects the change, the detection keeps its current status and the response carries the error, so you can retry. See [Mark a finding as a false positive](/docs/vulnerability-details/marking-false-positive). **Access:** Scope: `detections:update` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: detectionId in: path required: true schema: type: string description: The detection's ID, from `detectionId` in the list of detections. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateDetection' example: status: RISK_ACCEPTED comments: Accepted by the security team until the endpoint is retired. riskAcceptedEndDate: '2026-12-31' description: The new status and reason, or the new CVSS score. To apply the same status to several detections, list them in `detectionIds`. responses: '200': description: The detection is updated. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/owasp-coverage: get: operationId: getOwaspCoverage summary: Get OWASP coverage for an environment tags: - Detections description: 'Returns the environment''s detections counted against each category of the OWASP API Security Top 10 (2023), plus Injection (`API8:2019`). It is the data behind the console''s **OWASP Coverage** report. Use it for compliance reporting or to track risk by category across releases. The response has one entry per category, including categories with no detections. **Access:** Scope: `scan:get` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: excludeDetectionsWithStatus in: query required: false schema: type: array items: type: string description: Detection statuses to leave out of the counts, for example `DISMISSED`. Repeat the parameter for several statuses. responses: '200': description: 'One entry per category: API1 to API10 of the 2023 list, plus `API8:2019` (Injection). `owaspRank` is the category code, such as `API1:2023`, and `owaspRisk` its name. `activeVulCount`, `resolvedVulCount` and `riskAcceptedVulCount` count detections by status, and `vulnerableEpCount` counts affected endpoints. `cvssScore` and `cvssQualifier` give the category''s severity and are null when it has no detections.' content: application/json: schema: type: array items: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/scan-profiles: get: operationId: listScanProfiles summary: List scan profiles tags: - Scan Profiles description: 'Returns the scan profiles saved on an environment. Call it to find a `profileId` to pass to `startScan`, or to review what each profile scans. The console shows the same list under **Scan Profiles**. **Access:** Scope: `scan-profile:get` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' responses: '200': description: The environment's scan profiles, under `scanProfiles`. content: application/json: schema: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' post: operationId: createScanProfile summary: Create a scan profile tags: - Scan Profiles description: 'Saves a named, reusable scan scope on an environment and returns its `profileId`. Use profiles to keep pipeline scans consistent, or to scan a fixed subset of endpoints. `name` and at least one endpoint ID are required. Optionally set the test `categories`, the credential (`authId`), and the hosted agent (`agentId`) that scans using this profile should use. See [Scan profiles](/docs/scan-profiles). **Access:** Scope: `scan-profile:write` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScanProfileData' example: name: smoke endpoints: - ep-1 - ep-2 categories: - BOLA authId: a1b2c3d4 description: The profile. `id` is assigned by APIsec; omit it. responses: '200': description: Profile created. The body carries the new `profileId`. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/scan-profiles/{profileId}: get: operationId: getScanProfile summary: Get a scan profile tags: - Scan Profiles description: 'Returns one scan profile: its endpoints, categories, credential, and hosted agent. Call it to check a profile''s scope before you start a scan with it. **Access:** Scope: `scan-profile:get` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: profileId in: path required: true schema: type: string description: The scan profile's ID, from `listScanProfiles` or the create response. responses: '200': description: The scan profile. content: application/json: schema: $ref: '#/components/schemas/ScanProfileData' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' put: operationId: updateScanProfile summary: Update a scan profile tags: - Scan Profiles description: 'Replaces a scan profile with the body you send. Send the complete profile; fields you omit are not kept. Scans already started are unaffected; the next scan that names this profile uses the new scope. **Access:** Scope: `scan-profile:write` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: profileId in: path required: true schema: type: string description: The scan profile's ID, from `listScanProfiles` or the create response. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScanProfileData' description: The complete replacement profile. responses: '200': description: Profile updated. The body carries the `profileId`. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' delete: operationId: deleteScanProfile summary: Delete a scan profile tags: - Scan Profiles description: 'Deletes a scan profile from an environment. A pipeline or scan request that still names this `profileId` fails after deletion, so update those first. **Access:** Scope: `scan-profile:write` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: profileId in: path required: true schema: type: string description: The scan profile's ID, from `listScanProfiles`. responses: '200': description: Profile deleted. content: application/json: schema: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/schedulesWindow: get: operationId: listScheduleWindows summary: List scan schedules tags: - Scan Schedules description: 'Returns the scan schedules on an environment, the same list the console shows under **Scan Schedules**. Each entry includes its `scheduleId`, frequency, time, time zone, scope, and the next run time in `nextExecutionTime`. **Access:** Scope: `schedule:get` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' responses: '200': description: The environment's schedules, under `instanceScheduleWindows`. content: application/json: schema: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' post: operationId: createScheduleWindow summary: Create a scan schedule tags: - Scan Schedules description: 'Creates a recurring scan of an environment and returns the new schedule''s ID. Use it for continuous coverage between releases, alongside scans triggered from your pipeline. Set `frequency` to `daily`, `weekly`, or `monthly`, and `time` as `HH:mm` in 24-hour form in the schedule''s `timeZone`. Weekly schedules also need `dayOfWeek`; monthly schedules need `dayOfMonth`. An environment can have at most five schedules. See [Schedule scans](/docs/schedule-scans). **Access:** Scope: `schedule:write` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InstanceScanScheduleWindowRequest' example: scheduleName: nightly frequency: DAILY time: 02:00 timeZone: UTC +00:00 endpoints: [] categories: [] scanWithAuthId: a1b2c3d4 description: 'The schedule: name, timing, and the scope each run uses.' responses: '200': description: Schedule created. The body is the new schedule's ID. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/schedulesWindow/{scheduleId}: get: operationId: getScheduleWindow summary: Get a scan schedule tags: - Scan Schedules description: 'Returns one scan schedule, including its timing, scope, and next run time. The schedule is returned in the same list shape as `listScheduleWindows`, with a single entry. **Access:** Scope: `schedule:get` · Roles: ADMIN, USER, VIEWER, GLOBAL_VIEWER' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: scheduleId in: path required: true schema: type: string description: The schedule's ID, from `listScheduleWindows` or the create response. responses: '200': description: The schedule, as the single entry of `instanceScheduleWindows`. content: application/json: schema: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' put: operationId: updateScheduleWindow summary: Update a scan schedule tags: - Scan Schedules description: 'Replaces a scan schedule with the body you send. Send the complete schedule, including timing and scope; fields you omit are not kept. The next run time is recalculated from the new timing. **Access:** Scope: `schedule:write` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: scheduleId in: path required: true schema: type: string description: The schedule's ID, from `listScheduleWindows`. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InstanceScanScheduleWindowRequest' description: The complete replacement schedule. responses: '200': description: Schedule updated. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' delete: operationId: deleteScheduleWindow summary: Delete a scan schedule tags: - Scan Schedules description: 'Deletes a scan schedule so it no longer runs. Scans the schedule already started are unaffected, and their results stay in Scan History. **Access:** Scope: `schedule:write` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' - name: scheduleId in: path required: true schema: type: string description: The schedule's ID, from `listScheduleWindows`. responses: '200': description: Schedule deleted. content: application/json: schema: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v1/applications/{applicationId}/instances/{instanceId}/preferred-agent: put: operationId: setPreferredAgent summary: Set an environment's default hosted agent tags: - Hosted Agents description: 'Sets the environment''s **Default Hosted Agent**, the console''s **Select Default Hosted Agent** action. APIsec uses this agent to reach the environment when a request does not name one, for example a scan started without `scanWithAgent`. Set it for environments whose host is reachable only inside your network. The agent must be `ACTIVE`. Deleting the agent later clears it from every environment that used it as the default. See [Do I need a hosted agent?](/docs/do-i-need-a-hosted-agent). **Access:** Scope: `app:create` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: application/json: schema: type: object required: - agentId properties: agentId: type: string description: ID of an `ACTIVE` hosted agent, from the list of hosted agents. description: '`agentId`: the ID of an `ACTIVE` hosted agent, from `listHostedAgents`.' responses: '200': description: Default hosted agent set. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' delete: operationId: clearPreferredAgent summary: Remove an environment's default hosted agent tags: - Hosted Agents description: 'Removes the environment''s **Default Hosted Agent**, the console''s **Remove default agent** action. Afterwards, APIsec chooses how to reach the environment automatically unless a request names an agent. Call it before you decommission an agent, or when an environment''s host becomes reachable from the internet. **Access:** Scope: `app:create` · Roles: ADMIN, USER · Requires Edit permission on the application' parameters: - $ref: '#/components/parameters/ApplicationId' - $ref: '#/components/parameters/InstanceId' responses: '200': description: Default hosted agent removed. content: application/json: schema: type: object additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' tags: - name: Authentication description: Exchange an OAuth client credential for a short-lived access token. You create OAuth client credentials, and Personal Access Tokens, on the **API Credentials** page of the console. The two are interchangeable API credentials. For CI/CD pipelines, prefer short-lived OAuth tokens over long-lived Personal Access Tokens. See [API Credentials](/docs/api-token). - name: Applications description: 'An application is an API you have onboarded to APIsec. APIsec builds its model of the API — endpoints, methods, parameters and payloads — from the source you register it from: an OpenAPI spec, a Postman collection, a GraphQL schema, or captured traffic (HAR, Burp XML, mitmproxy). The typical workflow is register → add or confirm environments → configure authentication → scan. In CI/CD, register with an `externalId` so that every pipeline run resolves to the same application instead of creating a new one. See [Onboarding sources](/docs/onboarding-sources).' - name: Environments description: An environment is one deployment of an application that APIsec tests, identified by its host URL — for example staging and production. The API calls an environment an `instance` in paths and IDs (`instanceId`). Authentication, headers, endpoints, scans and detections all belong to an environment, so most calls after registration take both an `applicationId` and an `instanceId`. See [Manage applications and environments](/docs/manage-applications-and-environments). - name: Endpoints description: Endpoints are the operations APIsec tests in an environment, each identified by an HTTP method and a path. They come from the application's spec, and you can add or delete them by hand when the spec is incomplete or out of date. Use the endpoint `id` values from the list call when you delete endpoints. See [Manage endpoints](/docs/manage-endpoints). - name: Authentication Configurations description: 'An authentication configuration tells APIsec how to sign in to *your* API while it scans an environment. The console calls these **Credentials**. Authenticated scans reach the endpoints where authorization flaws live. The usual workflow: create a configuration, test it with `testCreds`, then pass its ID as `scanWithAuthId` when you start a scan. See [Configure authentication](/docs/setting-up-auth).' - name: Scans description: A scan runs APIsec's security tests against the endpoints of one environment and records detections. From a pipeline you start a scan, poll it until it reaches a terminal status, then read its detections to pass or fail the build. Scans started with an API credential appear in the console's Scan History with the trigger source `CI_CD`. See [CI/CD integration](/docs/ci-cd-integration). - name: Scan Profiles description: 'A scan profile is a saved, reusable scan scope for one environment: which endpoints and test categories to run, which credential to use, and which hosted agent runs the scan. Create a profile once, then name it with `profileId` when you start a scan. See [Scan profiles](/docs/scan-profiles).' - name: Scan Schedules description: 'A scan schedule runs scans of one environment automatically, daily, weekly, or monthly, at a set time in a set time zone. Each schedule carries its own scope: endpoints, categories, credential, and hosted agent. An environment can have up to five schedules. See [Schedule scans](/docs/schedule-scans).' - name: Detections description: A detection is one finding from one security test against one endpoint in an environment. The console shows detections on the **Vulnerabilities** tab. Detections belong to an environment, not to the application, so staging and production keep separate findings. Read them after a scan to gate a build or export results. Triage them as Risk Accepted or False Positive, and raise tickets in the environment's issue tracker. See [Viewing and understanding vulnerabilities](/docs/vulnerability-tab). - name: Issue Tracker description: An issue tracker carries detections out of APIsec into Jira, Azure DevOps or ServiceNow, so fixes land in the backlog your engineers already use. You create the tracker connection once in the console under **Integrations**, then attach it to each environment that should raise tickets. With automatic sync on, each scan opens tickets for new detections, and tickets close or reopen as detections change status. See [Integrations](/docs/integrations). - name: Hosted Agents description: 'A hosted agent is a container you run inside your own network so that APIsec can scan APIs its cloud cannot reach. It connects outbound only, on TCP 443. The usual workflow: create an agent, download its install command, run it on a host in your network, then wait for the agent to report `ACTIVE`. Agents created with an ADMIN credential are shared across your tenant; other agents are private to the user who created them. See [How hosted agents work](/docs/Hosted-Agents/understanding).' - name: Metadata Tags description: Metadata tags are tenant-wide fields that administrators define and assign to environments — for example a **Data Classification** field with the values `Public`, `Internal` and `Confidential`. They let you organize and search applications, and APIsec includes them on tickets it creates in a connected ServiceNow issue tracker. Define a field once, then assign its values to environments in bulk. The console shows them under **Manage Metadata Tags**. - name: Teams description: A team is a group of users within a business unit. Sharing an application with a team gives every member access to it, with **View** or **Edit** permission. Teams are created and managed in the console. These read-only operations let you see which teams exist and who belongs to them, for example to work out why a credential can see some applications but not others. See [Teams](/docs/teams).