Export Activity API

This document describes the API contracts and expected output data schemas for the Security Copilot Admin Export APIs.

Export APIs provide workspace administrators with the ability to export prompts and prompt responses in a paginated format.

Authentication and Authorization

• Authorization: Bearer token authentication
• Required Permissions: Workspace Owner / Admin

Authenticating with a Service Principal

1. Create an app registration (for example, use a name like mysecuritycopilotexportapp).

   • Use the Microsoft Entra ID quickstart: Register an app (portal).

   • If you prefer CLI, create the identity via the tutorial: Create a service principal (Azure CLI).

   • Add credentials to the app registration as needed: Add credentials (client secret/cert). For a step‑by‑step client‑secret creation, see Create client secret (explicit steps) or the portal guide, Register an app and create a Service Principal (portal).

2. Add the new Service Principal as an Owner in Security Copilot role assignments

   See, Security Copilot roles and assignments. Security Copilot supports assigning permissions to role‑assignable groups (RAGs), so create a RAG and then add your Service Principal (SP) to it as follows:

   • Create a role‑assignable group

   • Add the SP to the group (pick either): Portal—Manage groups (add members) or API—Microsoft Graph: Add group member

3. Retrieve a bearer token for your service principal.

   Example using Azure CLI and a client secret:

   # Login as service principal (supports no-subscription tenants)
   az login --service-principal -u 94e67e0c-7c41-4f5b-b5ae-f5b5918e2382 -p <client-secret> --tenant 536279f6-15cc-45f2-be2d-61e352b51eef --allow-no-subscriptions
   
   # Retrieve access token for Security Copilot (v1 resource pattern)
   az account get-access-token --resource https://api.securitycopilot.microsoft.com
   

References:

• Sign in as SP (CLI)
• Get access token (CLI)
• .default scope explained

Authenticating as a User

Ensure you're an owner, similar to step 2, and retrieve a bearer token scoped to Security Copilot.

Example using Azure CLI (v2 pattern with /.default):

az account get-access-token --scope https://api.securitycopilot.microsoft.com/.default

Reference:

Get access token (CLI) and .default scope.

Response as a Non-Owner

For non-owners, the following response is returned for API calls:

{
  "message": "Your role doesn\u0027t have access to the info requested. Contact a Security Administrator to change your role or try again with a different account. Learn more about copilot",
  "code": "403",
  "traceId": "0HNF1M54NKVJ3:00000041",
  "error": {
    "message": "Your role doesn\u0027t have access to the info requested. Contact a Security Administrator to change your role or try again with a different account. Learn more about copilot",
    "copilotErrorId": "doesNotHaveAccessToSecurityCopilot",
    "code": "403",
    "innerError": {
      "message": null,
      "date": "2025-08-22T19:32:04.4726177Z",
      "correlationId": "a83f0049-7f81-4a56-bf4c-f58d6ad4dd97"
    },
    "traceId": "0HNF1M54NKVJ3:00000041"
  }
}

API Endpoints

1. Prompts Export API

Endpoint

https://api.securitycopilot.microsoft.com/exports/prompts

GET /exports/prompts

Query Parameters

N/A

Request Example

GET /exports/prompts?sessionCount=500&startDate=2024-01-01T00:00:00Z&endDate=2024-12-31T23:59:59Z
Authorization: Bearer <token>

Response Schema

Success Response - (200 OK)

{
  "workspaceId": "string",
  "workspaceName": "string",
  "tenantId": "string",
  "prompts": [
    {
      // Prompt object schema (see Framework.Models.Prompt)
    }
  ],
  "sessionsContinuationToken": "string?",
  "totalCount": "integer?",
  "sessionCount": "integer"
}

Error codes and messages

2. Evaluations Export API

Endpoint

https://api.securitycopilot.microsoft.com/exports/evaluations

GET /exports/evaluations

Query Parameters

Request Example

GET /exports/evaluations?sessionCount=200&continuationToken=abc123
Authorization: Bearer <token>

Response Schema

Success Response - (200 OK)

{
  "workspaceId": "string",
  "workspaceName": "string",
  "tenantId": "string",
  "evaluations": [
    {
      // Evaluation object schema
    }
  ],
  "sessionsContinuationToken": "string?",
  "totalCount": "integer?",
  "sessionCount": "integer"
}

Error codes and messages

Data Models

Base Response Properties

Both export APIs return responses with these common properties:

Pagination

Both APIs support cursor-based pagination:

1. Initial Request: Make request without continuationToken.
2. Subsequent Requests: Use sessionsContinuationToken from the previous response.
3. End of Data: When sessionsContinuationToken is null, no more data is available.

Pagination Example

First request

GET /exports/prompts?sessionCount=100

Response includes continuationToken

{
  "sessionsContinuationToken": "[{\"compositeToken\":{\"token\":null,\"range\":{\"min\":\"05C1D1D5378D58\",\"max\":\"05C1D3CFCBB964\"}},\"resumeValues\":[\"2025-08-01T23:49:27.8981554+00:00\"],\"rid\":\"xQAMAIZUJBs7BEAAAADABQ==\",\"skipCount\":1}]",
  "prompts": [...],
  // ... other properties
}

Next request using token (URL encoded)

GET /exports/prompts?sessionCount=100&continuationToken=%5B%7B%22compositeToken%22%3A%7B%22token%22%3Anull%2C%22range%22%3A%7B%22min%22%3A%2205C1D1D5378D58%22%2C%22max%22%3A%2205C1D3CFCBB964%22%7D%7D%2C%22resumeValues%22%3A%5B%222025-08-01T23%3A49%3A27.8981554%2B00%3A00%22%5D%2C%22rid%22%3A%22xQAMAIZUJBs7BEAAAADABQ%3D%3D%22%2C%22skipCount%22%3A1%7D%5D

References

• Register an app (portal)
• Create SP (CLI tutorial)
• Add credentials (client secret/cert)
• Create client secret (explicit steps)
• (Alt) Create client secret in portal
• Security Copilot roles & assignments)
• Add Service Principal to a group (portal)
• Add Service Principal to a group (API)
• Sign in as SP (CLI)
• Get access token (CLI)