# Hookshot™ for Customers Hookshot™ helps your team connect company tools, watch for live events, and run AI-powered automations called **Proteges**. A Protege is a workflow you describe in plain language: 1. What starts it 2. What it decides 3. What it produces Hookshot then helps you connect the right integrations, validate trigger and tool access, and verify what happened in the **Event Feed** and **Audit** views. {% hint style="info" %} Use this documentation if you are a third-party customer using Hookshot in your workspace. This site is not the internal developer reference for the Hookshot codebase. {% endhint %} ## Start Here * [Product overview](/overview) * [Quickstart for power users](/overview/quickstart-power-user) * [Quickstart for automation engineers](/overview/quickstart-engineer) * [Go-live checklist](/overview/go-live-checklist) * [Release notes](/2026-05) ## Learn the Basics * [Glossary](/glossary) * [How Hookshot works](/glossary/how-hookshot-works) ## Build and Launch * [Create a Protege](/create-a-protege) * [Builder patterns](/create-a-protege/builder-patterns) * [Recipes](/create-a-protege/recipes) * [Readiness and blockers](/create-a-protege/readiness-and-blockers) ## Connect Integrations * [Integrations overview](/integrations) * [Slack](/integrations/slack) * [GitHub](/integrations/github) * [Asana](/integrations/asana) ## Operate with Confidence * [Event Feed](/event-feed) * [Audit](/event-feed/audit) * [Troubleshooting](/event-feed/troubleshooting) * [Safe rollout](/event-feed/safe-rollout) ## Manage Your Workspace * [Workspace settings](/workspace-settings) * [Teams and people](/workspace-settings/teams-and-people) * [Security and permissions](/workspace-settings/security-and-permissions) ## How Hookshot Fits Together 1. You connect an integration. 2. You create a Protege. 3. You confirm trigger access and tool access. 4. Hookshot receives an event or schedule tick. 5. The Protege runs or is skipped. 6. You verify the result in Event Feed and Audit. ## Get Help For support, email ****. {% hint style="success" %} **Tip:** If you are new to Hookshot, start with the power-user quickstart even if you are technical. It gives you the fastest path to a working mental model. {% endhint %} # Getting Started ## What this is This page explains the customer-facing Hookshot™ model: **Proteges**, **Integrations**, **Event Feed**, **Audit**, and **Settings**. ## When to use it Read this page before building your first Protege or when you need a fast refresher on how Hookshot fits together. ## What you need first * A Hookshot workspace * Access to at least one external app you want to connect * Permission to create or edit Proteges in your workspace ## Steps ### 1. Understand the core objects * A **Protege** is an automation you define in plain language. * An **Integration** connects Hookshot to tools like Slack, GitHub, Linear, or Asana. * **Trigger Access** controls what can start a Protege. * **Tool Access** controls what a Protege can do after it starts. * The **Event Feed** shows incoming activity and whether Proteges ran. * **Audit** shows the history and outcome of Protege runs. {% hint style="info" %} Think of Hookshot as a control plane for automations. You describe the workflow, connect the right systems, and then use Event Feed and Audit to verify behavior. {% endhint %} ### 2. Learn the three questions every Protege answers 1. What starts it? 2. What does it decide? 3. What does it produce? If you can answer those three questions clearly, you are ready to draft a useful Protege. ### 3. Map the main dashboard sections ![Empty Proteges view](/files/VlwYzA3T3i9VjCq7iA1j) * **Proteges**: create drafts, use the Builder, review plans, manage setup, enable, disable, and refine automations * **Integrations**: browse supported apps, connect accounts, review tool access, review trigger access, and repair broken connections * **Event Feed**: inspect live events, scheduled activity, routing decisions, and whether Hookshot ran, skipped, or is still evaluating * **Audit**: inspect fleet runs, Protege-specific history, run timelines, tool usage, logs, feedback, and analytics * **Settings**: manage workspace profile, billing, usage, teams, people, and access controls ## How to verify You understand the model well enough to continue when you can explain: * Which app or schedule starts your Protege * Which action or outcome the Protege should produce * Where you will confirm activity in Event Feed * Where you will confirm success or failure in Audit * Which team or person owns the workflow after launch ## Common failures * Treating a Protege like a chat bot instead of an automation with a clear trigger * Confusing Trigger Access with Tool Access * Turning on a Protege before checking readiness blockers * Looking only at Audit when the Event Feed is the faster place to confirm whether the event arrived ## Next step * [Quickstart for power users](/overview/quickstart-power-user) * [Quickstart for automation engineers](/overview/quickstart-engineer) * [Glossary](/glossary) # Quickstart for Power Users ## What this is This quickstart helps a non-technical but high-agency user create a first Protege and confirm that it works. ## When to use it Use this path if you want a working automation quickly and do not need deep operational detail yet. ## What you need first * A Hookshot™ workspace * Access to one supported app such as Slack, GitHub, Linear, or Asana * A simple workflow goal with one clear trigger and one clear outcome {% hint style="success" %} **Tip:** Start with a narrow workflow. A first Protege should watch one source and produce one obvious result. {% endhint %} ## Steps ### 1. Pick a simple workflow Good first examples: * Summarize important Slack activity into one destination * Create or update work items when an issue appears in GitHub or Asana * Send a reminder when a tracked task still needs attention ### 2. Connect the app you need ![Connect Slack in Integrations](/files/WLIgubDI5cSTJYozeTOG) 1. Open **Integrations**. 2. Choose the app you need. 3. Complete the connection flow. 4. Check both **Trigger Access** and **Tool Access** for that integration. {% hint style="warning" %} If the integration connects but the Protege still cannot start or act, the usual cause is incomplete Trigger Access or Tool Access, not the Protege itself. {% endhint %} ### 3. Create a Protege ![Create a Protege wizard](/files/so1Cq442J0Rzfjq1CQV0) Open **Proteges**, then choose **New Protege**. In the wizard, describe the Protege in plain language: * **What starts it:** the event or schedule * **What it decides:** the logic or conditions * **What it produces:** the action, message, or update Example: > When a new task is created in Asana, post a summary to the right Slack channel. ### 4. Review setup blockers Before you enable anything, confirm: * The required integration is connected * The trigger source is ready * Any setup blocker is resolved * The Protege has a clear result you can verify ### 5. Trigger the workflow * Use a live event from the connected app, or * Use a schedule if the Protege is time-based ### 6. Check Event Feed first Open **Event Feed** and confirm: * The event arrived * The right Protege was associated with it * The status moved to a useful outcome such as `ran` ### 7. Check Audit second Open **Audit** and confirm: * A run exists for the Protege * The run result matches what you expected * The outcome is understandable enough to share with a teammate ## How to verify ### You’re done when... * The integration shows as connected * The Protege has no unresolved setup blockers * Event Feed shows the event and the Protege response * Audit shows the resulting run and outcome ## Common failures * The event never appears in Event Feed * The event appears but the Protege is `skipped` * The run exists but the outcome is not the result you expected * The Protege is too broad and reacts to more items than intended ## Next step * [Go-live checklist](/overview/go-live-checklist) * [Create a Protege](/create-a-protege) * [Event Feed](/event-feed) # Quickstart for Automation Engineers ## What this is This quickstart is the fastest path to a production-ready first Protege for an engineer owning internal automation inside a company. ## When to use it Use this path if you care about safe rollout, least privilege, observability, and operational clarity from the start. ## What you need first * A Hookshot™ workspace * Permission to connect apps and manage Proteges * Access to the source system and destination system for your workflow * A workflow with a clear source, scope, and expected outcome {% hint style="info" %} Keep the first rollout scoped to one team, project, repo, channel, or equivalent boundary. Narrow scope is the easiest control for reducing blast radius. {% endhint %} ## Steps ### 1. Define the operating boundary Write these down before you build: * Source system * Exact trigger condition * Output destination * Allowed actions * Owner of the automation * Fast rollback method ### 2. Connect integrations with least privilege 1. Open **Integrations**. 2. Connect only the apps required for the workflow. 3. Review **Trigger Access** for what can start the Protege. 4. Review **Tool Access** for what the Protege can do. 5. Prefer the smallest connection scope that still satisfies the workflow. ### 3. Create the Protege with explicit constraints Your description should include: * What starts it * What it decides * What it produces * What it must never do * The narrowest practical project, repo, channel, or team scope ### 4. Resolve readiness blockers before enabling Confirm: * Connection health is good * Trigger source is live and mapped correctly * Tool access matches the expected actions * No blocker remains in setup ### 5. Run a controlled test Use a known-safe live event or schedule window. Then validate: * Event Feed receives the event * The intended Protege is associated with it * Audit shows the corresponding run * The outcome is correct and limited to the intended scope ### 6. Prepare rollback Before broad rollout, document: * How to disable the Protege * Which integration might need repair if behavior changes * Which team should review future changes ## How to verify ### You’re done when... * The integration scope is as narrow as practical * Trigger Access and Tool Access both match the workflow * Event Feed shows the expected event path * Audit confirms the run and result * You can explain how to pause the Protege if needed ## Common failures * Connections are valid but overscoped * Trigger source is connected to the wrong workspace or resource * Event Feed shows an event but the Protege is `unevaluated` or `skipped` * Audit shows a run, but the output is broader than intended ## Next step * [Safe rollout](/event-feed/safe-rollout) * [Security and permissions](/workspace-settings/security-and-permissions) * [Troubleshooting](/event-feed/troubleshooting) # Go-Live Checklist ## What this is This page is the final readiness checklist before you rely on a Protege in a live workflow. ## When to use it Use it after building or editing a Protege and before expanding usage to a wider team. ## What you need first * A drafted or published Protege * At least one connected integration or schedule * Access to Event Feed and Audit ## Steps ### 1. Confirm setup readiness * No unresolved setup blockers remain * Required integrations are connected * Required trigger sources are live * Required tool access is present ### 2. Confirm workflow clarity * The Protege has one clear owner * The trigger is narrow enough to avoid noisy activation * The expected output is concrete and observable * The disable or pause path is understood ### 3. Confirm observability * You know which Event Feed event should appear first * You know which Audit run should appear next * You know what success looks like in both places ### 4. Confirm governance * Team members who need visibility have access * Workspace settings are appropriate for the team * Anyone responsible for support knows where to debug ## How to verify ### You’re done when... * Event Feed shows the expected incoming event or schedule activity * The Protege reaches the expected status * Audit shows the run and outcome you planned for * The team knows how to pause the Protege if necessary ## Common failures * Going live before verifying Trigger Access * Assuming connection success means runtime success * Forgetting to test the exact event path that should activate the Protege * Enabling a Protege without a clear owner ## Next step * [Readiness and blockers](https://github.com/tryprotege/hookshot-private/blob/main/docs/build/readiness-and-blockers.md) * [Event Feed](/event-feed) * [Audit](/event-feed/audit) # Concepts ## Artifact An **artifact** is a note, attachment, or link that provides background for a task, helping Proteges make better decisions. ## Audit **Audit** shows Protege run history and outcomes so you can confirm what happened. Audit includes fleet-wide runs, Protege-specific history, run detail timelines, tool usage, logs, teaching notes, and analytics. ## Auto Top-Up **Auto top-up** automatically purchases a credit pack when your balance falls below a threshold you configure. ## Chat **Chat** is the feature that lets you talk directly to Hookshot or a Protege inside Slack threads and Asana task comments by mentioning `@hookshot`. ## Connected An integration or trigger source is **connected** when Hookshot can use it for the intended workflow. ## Conversation Binding A **conversation binding** maps an external conversation (Slack thread or Asana task) to a chat session in Hookshot, maintaining context across messages. ## Credit A **credit** is the unit of consumption for Protege runs. Each run consumes credits based on the AI model's token usage. ## Credit Pack A **credit pack** is a one-time purchase that adds credits to your workspace balance. ## Decision In the Work Hub, a **decision** is an approval or recommendation attached to a task. Proteges can request decisions when they need human judgment. ## Dispatching In the Event Feed, **dispatching** means Hookshot is still working through the event and the final run state is not ready yet. ## Drift Reconciliation **Drift reconciliation** is a periodic full sync between the Work Hub and an external provider that catches changes that real-time listeners or polling may have missed. ## Environment Link An **environment link** pairs a production workspace with a sandbox workspace. Each workspace can belong to only one environment pair. The sandbox is used for testing Protege configurations before promoting them to production. ## Event Feed The **Event Feed** shows incoming events and how Hookshot responded to them. ## Outcome An **outcome** is the result of a run. It is the answer to "what happened after the Protege ran?" ## Pending Write A **pending write** is a Protege-authored change that is waiting for human approval before it is applied. Pending writes are created when the write policy requires approval. ## Project A **project** is a named set of tasks in the Work Hub, with optional custom fields, completion rules, and provider sync. ## Promotion **Promotion** is the process of deploying a Protege's configuration from a sandbox workspace to its linked production workspace. Promotion copies behavior settings, tool access, and schedules while preserving production credentials and run history. ## Provider Sync **Provider sync** is the process of synchronizing data between the Work Hub and an external provider like Asana or Jira. This includes importing records and, for providers that support it, pushing outbound changes. ## Ready **Ready** means the integration or Protege has the required setup in place for live use. ## Run A **run** is one execution of a Protege. Runs can be **standard** (event or schedule triggered) or **chat** (triggered by a conversation mention). Run statuses include `queued`, `running`, `success`, `failure`, and `dead_letter`. ## Sandbox Workspace A **sandbox workspace** is a dedicated testing workspace linked to a production workspace. Proteges can be configured and tested in the sandbox, then promoted to production. Team and people administration in the sandbox is inherited from the production workspace. ## Schedule A **schedule** is a time-based way to start a Protege instead of waiting for an external event. ## SE Access **SE Access** (Solutions Engineering Access) is a controlled overlay that allows Protege AI staff to view or edit your workspace configuration for support purposes. ## Setup Blocker A **setup blocker** is anything that still prevents a Protege from being fully ready, such as a missing connection, missing trigger source, or missing required configuration. ## Skill A **skill** is a reusable markdown instruction document (SKILL.md) that can be assigned to a Protege to give it specific behavior rules. Skills live in the Skills Hub and are scoped to a team. ## Skills Hub The **Skills Hub** is the team-scoped library where skills are created, managed, and assigned to Proteges. ## Skipped In the Event Feed, **skipped** means Hookshot saw the event but did not run the Protege for that event. ## System Chat **System Chat** is the built-in Hookshot responder that handles direct @mention conversations without needing a user-created Protege. ## Tool Access **Tool Access** controls which actions a Protege can take after it starts. ## Trigger Access **Trigger Access** controls which providers are allowed to start a Protege. ## Trigger Source A **trigger source** is the live source of events that can start a Protege. Some trigger sources are automatic (Hookshot creates and maintains them for you, such as the Fathom transcript trigger). Others are manual (you create them yourself on the Integrations page). Managed trigger sources display a "Managed by Work Hub project" label when a Work Hub project owns them. ## Unevaluated In the Event Feed, **unevaluated** means the event has not yet been fully processed into a final decision you can rely on. ## Write Policy The **write policy** controls whether a Protege's changes are applied immediately (`autonomous`) or require human approval (`approval_required`). {% hint style="info" %} If you see a term in the UI and are not sure what action to take next, look for that term again in [Event Feed](/event-feed), [Audit](/event-feed/audit), or [Troubleshooting](/event-feed/troubleshooting). Those pages turn labels into actions. {% endhint %} # How Hookshot Works ## What this is This page explains the customer mental model for Hookshot without diving into internal architecture. ## When to use it Use this page when you want to understand the sequence from incoming event to verified outcome. ## What you need first * Familiarity with the terms in the [glossary](/glossary) ## Steps ### 1. Something starts the workflow A Protege starts because of: * A live event from an integration, or * A schedule you configured ### 2. Hookshot checks whether the Protege should act Hookshot looks at: * The available trigger source * The Protege configuration * The connected tool access needed to complete the task ### 3. The Protege runs or is skipped Possible outcomes you may see: * `ran`: the Protege executed * `dispatching`: the event is still in progress * `skipped`: Hookshot chose not to run the Protege for that event * `unevaluated`: the event has not reached a final usable state yet ### 4. You verify what happened * Use **Event Feed** to confirm the event arrived and see the immediate status * Use **Audit** to inspect the run and outcome {% hint style="info" %} Event Feed answers "did Hookshot see the event and what happened next?" Audit answers "what did the Protege actually do?" {% endhint %} ### 5. How Proteges appear in external services When a Protege writes to an external service (Slack, Asana, GitHub, Linear), the output appears exactly as the AI model produces it. Hookshot does not add templates, signatures, footers, or attribution labels to agent output. For chat conversations specifically: * **Slack**: The Protege's response appears as a reply in the same thread. While the response is being generated, an `:eyes:` emoji reaction appears on the triggering message. * **Asana**: The Protege's response appears as a comment on the same task. While the response is being generated, a temporary "Hookshot is working on this..." comment appears and is automatically deleted once the response is posted. * **Asana rich text**: Proteges can produce HTML-formatted comments in Asana, which appear with rich text styling. If the Protege already posted a message directly, the auto-reply is skipped to avoid duplicate posts. The Protege's behavior and tone are controlled by its system prompt and assigned skill, not by a formatting template. To change how a Protege sounds in external services, update its behavior instructions. ## How to verify You understand the model well enough when you can point to: * The system that starts the Protege * The condition that decides whether the Protege should act * The product section where you will confirm success ## Common failures * Looking only at Audit when the event never arrived in Event Feed * Assuming a connected integration automatically means the trigger source is ready * Confusing a visible event with a confirmed successful run ## Next step * [Create a Protege](/create-a-protege) * [Event Feed](/event-feed) * [Audit](/event-feed/audit) # Build ## What this is This page explains how to create a Protege, review its plan, finish setup, and publish it. A Protege is an automation you describe in plain language. Hookshot™ turns that description into a reviewed plan with trigger access, tool access, schedules, and setup checks. ## When to use it Use this page when you are creating a new automation or editing an existing Protege from the Builder. ## What you need first * A clear workflow goal * Access to the apps the Protege should read from or write to * Permission to create or edit Proteges in your workspace ## Steps to create a Protege Hookshot™ creates a Protege through a four-step wizard. The wizard produces a reviewed plan with setup checks and a publish step. ### 1. Start from Proteges Open **Proteges**, then choose **New Protege**. ![Create a Protege wizard](/files/so1Cq442J0Rzfjq1CQV0) The wizard opens with four steps: Describe, Triggers, Tools, and Review. ### 2. Describe the outcome In the **What does this agent do?** field, describe what the Protege should produce and why. Include the three required details: * **What starts it:** an event, chat message, or schedule * **What it decides:** the condition, routing logic, or judgment it should apply * **What it produces:** the message, update, task, issue, or other action it should create Good first description: > When a new Asana task is created, summarize it and post the summary to the support triage Slack channel. You can also choose the model and connection type (Team or Personal) on this step. ### 3. Choose triggers ![Create a Protege triggers](/files/0VBE6QVn2E8vwyuGhq3I) Select what starts the Protege: * An event from a connected integration * A schedule * A chat mention Pick the narrowest scope that covers your workflow — one project, repo, channel, or team. ### 4. Grant tool access ![Create a Protege tools](/files/rhKkDU6nOhCenzKa4Fqz) Choose which tools the Protege is allowed to use after it starts. Grant only the tools the workflow needs. If the Protege should post to Slack but not read Slack history, grant the posting tool only. ### 5. Review and publish Review the complete configuration: * The trigger is correct and narrow * The tools match the intended actions * The outcome description is specific Publish when the configuration looks right. Resolve any setup blockers before going live. {% hint style="warning" %} If the wizard shows a setup blocker after review, go back to the relevant step and resolve it before publishing. A Protege with unresolved blockers cannot run automatically. {% endhint %} ## How to verify You are ready to publish when: * The plan matches your intended workflow * Required integrations are connected * Trigger Access and Tool Access are complete * Any schedule is enabled and scoped correctly * You know what event or schedule will test the Protege * You know where to check Event Feed and Audit afterward ## Common failures * Describing the desired result but not the trigger * Accepting a plan with broader access than intended * Publishing before required service connections are complete * Forgetting to add a schedule for a schedule-only Protege * Testing in Audit before confirming the event arrived in Event Feed ## Next step * [Builder patterns](/create-a-protege/builder-patterns) * [Skills Hub](/create-a-protege/skills-hub) * [Readiness and blockers](/create-a-protege/readiness-and-blockers) * [Event Feed](/event-feed) # Builder Patterns ## What this is This page describes common Protege patterns and when to use each one. ## When to use it Use this page before writing a Builder prompt or when you are deciding whether a workflow should be event-driven, scheduled, or chat-assisted. ## Patterns ### Event-driven Protege Use this when an external app event should start the workflow. Examples: * A GitHub pull request opens * A Linear issue changes priority * An Asana task receives a new comment * A Slack message arrives in a monitored channel Event-driven Proteges need Trigger Access for the source and Tool Access for any resulting action. ### Scheduled Protege Use this when Hookshot™ should run on a recurring schedule. Examples: * Send a weekday summary * Check stale work items every morning * Produce a weekly status update Scheduled Proteges need at least one enabled schedule. If the Protege only runs on schedules, setup will block publishing until a schedule exists. ### Chat-assisted Protege Use this when a connected chat surface should route conversation into Hookshot. Examples: * Receive a Slack message and decide whether to reply * Watch an Asana project or portfolio for comments that need follow-up Chat-assisted Proteges should stay narrowly scoped to the channels, projects, portfolios, or teams that should be monitored. ### Tool-writing Protege Use this when the Protege should create or update information in another app. Examples: * Create a Linear issue * Post a Slack message * Update an Asana task * Comment on a GitHub item Tool-writing Proteges require careful Tool Access review because they can change external systems. ### Review-first Protege Use this when you want to draft and inspect the workflow before enabling it. This is the safest first path for workflows with new integrations, new teams, or uncertain scope. ## How to choose Use an event-driven pattern when the workflow starts from live app activity. Use a scheduled pattern when the workflow starts from time. Use a chat-assisted pattern when conversation is the main source. Use a review-first pattern when the workflow is new, risky, or still being shaped. {% hint style="info" %} Many production Proteges combine patterns. For example, a Protege can be event-driven and tool-writing, or scheduled and tool-writing. The important part is making the trigger and allowed actions explicit. {% endhint %} ## How to verify You chose the right pattern when you can answer: * What starts the Protege? * What apps does it need to read from? * What apps can it write to? * What is the smallest safe scope? * Where will you confirm the result? ## Common failures * Treating a scheduled workflow like an event-driven workflow * Giving a tool-writing Protege broader access than it needs * Monitoring a whole workspace when one team, repo, project, or channel would work * Publishing before the trigger or schedule is ready ## Next step * [Create a Protege](/create-a-protege) * [Skills Hub](/create-a-protege/skills-hub) * [Chat](/create-a-protege/chat) * [Readiness and blockers](/create-a-protege/readiness-and-blockers) * [Safe rollout](/event-feed/safe-rollout) # Skills Hub ## What this is The Skills Hub is a Hookshot™ team-scoped library of reusable skill definitions you can assign to Proteges. A skill is a markdown document that gives a Protege specific instructions for how to behave during a run. ## When to use it Use the Skills Hub when you want to: * Create or manage reusable instruction sets for Proteges * Assign a skill to a Protege so it follows consistent behavior rules * Share a skill definition across Proteges in the same team ## What you need first * A workspace with at least one team * Permission to create or edit Proteges in your workspace ## Steps ### 1. Open the Skills Hub From **Proteges**, choose **Skills Hub**. The Skills Hub shows a catalog of all skills available to your current team. Skills are team-scoped: only skills belonging to your active team appear in the catalog. ### 2. Create a skill Choose **New skill** to open the skill editor. You can start from: * **A template suggestion**: Pick from rotating sets of starter templates, then customize the instructions * **Blank**: Write your own instructions from scratch Fill in the skill: * **Instructions** (required): The core behavior rules for the Protege. Write these as clear, step-by-step guidance. * **Name** (optional): If you leave this blank, Hookshot™ auto-generates a lowercase kebab-case name from your instructions * **Description** (optional): If you leave this blank, Hookshot auto-generates a short one-sentence description from your instructions {% hint style="info" %} When name or description are left blank, Hookshot uses AI to generate them from your instructions. You can always edit them afterward. {% endhint %} ### 3. Understand the SKILL.md format Every skill is stored as a `SKILL.md` file with YAML frontmatter and a markdown body: ```markdown --- name: deploy-staging description: Follow the staging deployment checklist before pushing license: MIT compatibility: opencode allowed-tools: mcp:slack:* metadata: version: '1.0' author: 'platform-team' --- ## Instructions 1. Check the current branch against the protected branch list 2. Verify all CI checks are passing 3. Post a summary to the deployment channel before proceeding ``` Frontmatter keys: `name`, `description`, `license`, `compatibility`, `allowed-tools`, and `metadata.*`. ### 4. Upload a skill package If you have an existing `SKILL.md` file, you can upload it directly: 1. From the Protege editor skills section, choose **Upload a package** 2. Paste or upload the `SKILL.md` content 3. Review the parsed frontmatter and validation checklist 4. Confirm to add it to your team's Skills Hub Uploaded skills are marked as **Imported** in the catalog. ### 5. Manage existing skills From the Skills Hub catalog you can: * **Preview** a skill to view its full SKILL.md content * **Download** the SKILL.md file for local editing or sharing * **Replace SKILL.md** with new content (paste or upload), with a two-step review flow * **Delete** a skill from the catalog (requires confirmation) ### 6. Assign a skill to a Protege A Protege can have at most one active skill at a time. To assign: 1. Open the Protege editor 2. In the Skills section, choose a skill from the catalog or create a new one 3. The skill's instructions are loaded into the Protege during each run To remove: Use the **Remove** action on the current skill card in the Protege editor. ### 7. Validate your skill Before saving, check the validation checklist: * Name is valid lowercase kebab-case (letters, numbers, hyphens only, no consecutive hyphens, max 64 characters) * Description is present and under 1024 characters * SKILL.md has valid YAML frontmatter with both `name` and `description` fields {% hint style="warning" %} Skill names must be unique within your team. The same name can exist in a different team within the same workspace, but not twice in the same team. {% endhint %} #### Skill sources Each skill in the catalog shows a source badge: | Source | Meaning | | ------------ | ----------------------------------------------------------- | | **Custom** | Built in-app via the instructions editor or SKILL.md editor | | **Imported** | Uploaded from a local SKILL.md file | | **GitHub** | Imported from a public GitHub URL (coming soon) | #### Team scoping Skills belong to the team that was active when you created them. Switching your active team changes which skills appear in the catalog. Two teams in the same workspace can each have a skill with the same name — they are independent. When a Protege runs, it loads the skill assigned to it for the current workspace and team. ## How to verify * The skill appears in the Skills Hub catalog for the correct team * The assigned skill shows on the Protege editor * The SKILL.md content matches your intended instructions * Name and description are accurate and descriptive ## Common failures * Writing instructions that are too vague for the Protege to follow consistently * Creating a skill in the wrong team context * Assigning a skill without reviewing the full SKILL.md content * Leaving the name blank and not reviewing the auto-generated result * Forgetting that only one skill can be active per Protege at a time ## Next step * [Create a Protege](/create-a-protege) * [Builder Patterns](/create-a-protege/builder-patterns) * [Integrations Overview](/integrations) # Chat ## What this is Hookshot™ Chat lets you talk directly to a Protege or to the built-in Hookshot responder inside Slack threads and Asana task comments by mentioning `@hookshot`. ## When to use it Use Chat when you want to: * Ask a question or give an instruction inside an existing Slack thread or Asana task * Get a response from Hookshot without creating a dedicated Protege * Continue a conversation where the work is already happening ## What you need first * A connected Slack or Asana integration with chat enabled * A team-scoped chat connection in the integration settings ## Steps ### 1. Enable chat on an integration For Slack or Asana: 1. Open **Integrations** 2. Select the integration 3. Enable chat in the integration detail view 4. Confirm the chat connection is team-scoped and active Chat connections are always team-scoped. They cannot be personal connections. ### 2. Invoke Hookshot in a conversation In Slack or Asana, mention Hookshot to start a conversation: * **Slack**: Use `@hookshot`, `@hookshotdev`, or `@composio` in a channel where the Slack bot is present * **Asana**: Include `@hookshot`, `@hookshotdev`, or `@composio` in a task comment {% hint style="info" %} Chat requires an explicit mention. Hookshot does not passively listen to all messages — it only responds when invoked. {% endhint %} ### 3. Understand System Chat vs Protege Chat Hookshot routes chat conversations to one of two targets: | Target | When it applies | Behavior | | ---------------- | ------------------------------------------------ | ----------------------------------------------------------------------- | | **System Chat** | No specific Protege is bound to the conversation | Built-in Hookshot responder handles the message using standard AI tools | | **Protege Chat** | A Protege is bound to the conversation | The Protege's skill, tools, and configuration drive the response | System Chat requires no setup beyond enabling chat on the integration. It is always available when chat is enabled. ### 4. Continue a conversation After the first mention, subsequent messages in the same thread or task continue the conversation with the same target. You do not need to mention `@hookshot` again in follow-up messages within the same thread. For Asana, follow-up comments that do not mention Hookshot are still processed if they are in a task where an active conversation binding exists. ### 5. Watch for in-progress indicators When Hookshot is processing a chat message, you will see: * **Slack**: An `:eyes:` emoji reaction appears on the triggering message while the response is being generated * **Asana**: A temporary comment reading "Hookshot is working on this..." appears and is automatically deleted once the response is posted ### 6. Review the response The response appears as a reply in the same Slack thread or as a comment on the same Asana task. If the Protege uses a tool to post the message directly, the auto-reply is skipped to avoid duplicate posts. You can verify chat activity in: * **Event Feed**: Shows the inbound chat event * **Audit**: Shows the chat run with tool usage and outcome ## Chat configuration Each integration with chat support has per-team configuration: * **Enabled/disabled**: Turn chat on or off for the team * **Coverage mode**: How Hookshot decides which conversations to monitor (currently `mention_anywhere`) * **Response mode**: How Hookshot replies (currently `reply_in_thread`) For Asana, you can select specific projects or portfolios for chat coverage. For Slack, confirm the correct channel boundary. ## How chat routing works 1. A user mentions `@hookshot` in Slack or Asana 2. Hookshot receives the event via the connected integration 3. The chat routing layer checks if an existing conversation binding exists for this thread or task 4. If a binding exists: the conversation continues with the bound target (System Chat or a specific Protege) 5. If no binding exists: a new conversation is created with System Chat or the first eligible Protege 6. The target Protege runs, and the response is posted back to the thread or task ## How to verify * Chat is enabled on the integration detail page * The chat connection shows as active and team-scoped * Mentioning `@hookshot` in the target channel or task produces a response * The response appears in the same thread or task * The run appears in Audit with `chat` execution mode ## Common failures * Enabling chat but not confirming the chat connection is active * Expecting Hookshot to respond without an explicit `@hookshot` mention * Using a personal connection instead of a team connection for chat (chat connections must be team-scoped) * Mentioning Hookshot in a channel or project that is outside the configured coverage * Checking only Slack or Asana for the response without confirming the run completed in Audit ## Next step * [Integrations Overview](/integrations) * [Slack](/integrations/slack) * [Asana](/integrations/asana) * [Create a Protege](/create-a-protege) # Recipes ## What this is Recipes are small starting points for common Hookshot™ Protege workflows. Use them as prompts to adapt, not as final production instructions. ## When to use it * When you want to create a Protege but are not sure where to start * When you need a working example to adapt for your own workflow * When you want to see what a good Builder prompt looks like ## What you need first * A Hookshot workspace * At least one connected integration relevant to the recipe * Permission to create Proteges in your workspace ## Steps ### 1. Slack triage summary #### Use when You want Hookshot to notice important Slack activity and summarize it for a team. #### Starting prompt > When a message in the support triage Slack channel looks urgent, summarize the issue, identify the customer impact, and post a short update to the support leads channel. #### Setup to verify * Slack is connected * The monitored channel is the intended channel * The destination channel is correct * Event Feed shows the message event * Audit shows the posted summary ### 2. GitHub pull request follow-up #### Use when You want a Protege to react to GitHub pull request activity. #### Starting prompt > When a pull request is opened in the repository, check whether it needs release-note attention and post a short reminder if it does. #### Setup to verify * GitHub is connected * The repo scope is correct * Trigger Access points to the intended pull request event * Audit shows any resulting message or update ### 3. Asana task comment response #### Use when You want Hookshot to watch Asana work and respond when a task comment needs attention. #### Starting prompt > When a new comment appears on an Asana task in the customer onboarding project, decide whether it needs follow-up and post a concise response or task update. #### Setup to verify * Asana is connected * The project or portfolio scope is correct * Trigger Access is ready or waiting for the first trigger event * Tool Access matches the allowed response path ### 4. Scheduled weekly summary #### Use when You want a recurring update without waiting for an external event. #### Starting prompt > Every Monday morning, summarize open high-priority work for the team and post a short status update to the weekly planning channel. #### Setup to verify * The schedule has the right time and timezone * The Protege has access to the tools it needs for the summary * The destination is narrow and correct * Audit shows the scheduled run after it fires ## How to verify You adapted a recipe correctly when: * The Protege has a clear trigger that matches your real workflow * The tools are scoped to the smallest practical boundary * Event Feed shows the expected event * Audit shows the expected run and outcome ## Common failures * Copying a recipe prompt without adapting the channel, project, or team names to your workspace * Using a recipe as a production Protege without testing with a safe event first * Choosing a recipe that spans too many integrations for a first Protege ## Next step * [Create a Protege](/create-a-protege) * [Integrations overview](/integrations) * [Event Feed](/event-feed) # Readiness and Blockers ## What this is Readiness checks explain whether a Protege is safe to save, test, or publish. Blockers are setup issues Hookshot™ finds before a Protege can run reliably. ## When to use it Use this page when a Protege cannot be published, cannot run automatically, or shows setup warnings after a Builder plan is accepted. ## Blockers you may see ### Complete basics The Protege needs a clear name and description. Fix it by adding enough context that a teammate can understand what the Protege owns. ### Add behavior instructions The Protege needs clear run-time rules. Fix it by describing what the Protege should decide, what it should produce, and what it should avoid. ### Connect required services One or more required integrations are not connected or need repair. Fix it by opening the integration and completing the connection or reconnection flow. ### Connect trigger services The Protege has a trigger, but the service that provides the trigger is not connected. Fix it by connecting the source integration before expecting automatic runs. ### Finish trigger setup The trigger is connected but still needs configuration, such as a project, repo, channel, team, or other provider-specific field. Fix it by filling the required trigger input in setup or Integrations. ### Waiting for first trigger event The trigger is registered, but Hookshot has not received the first matching event yet. Fix it by sending a known-safe event from the connected app, then checking Event Feed. ### Add a schedule The Protege is schedule-only but has no enabled schedule. Fix it by adding at least one schedule with the intended cron and timezone. ## Access checks ### Trigger Access Trigger Access controls what can start the Protege. Review it when: * No event appears in Event Feed * The wrong event starts the Protege * The Protege is skipped or unevaluated ### Tool Access Tool Access controls what the Protege can do after it starts. Review it when: * A run cannot complete the expected action * The plan includes a tool you did not intend to allow * The Protege writes to an external system {% hint style="warning" %} Tool Access deserves extra review for workflows that post messages, create issues, update tasks, or otherwise change another system. {% endhint %} ## How to verify ![Protege setup page with integration and trigger status](/files/NHv4tMlOADvd3ikk5CEU) You are ready to test when: * Required services are connected * Required trigger fields are complete * Schedule-only Proteges have a schedule * Tool Access matches the intended action * Event Feed can show the incoming event or scheduled run * Audit can show the resulting run ## Common failures * Connecting an app but not completing trigger setup * Adding tools before confirming the Protege needs them * Waiting in Audit for a run when no event has arrived * Publishing a schedule-only Protege without a schedule * Ignoring waiting trigger states during first setup ## Next step * [Create a Protege](/create-a-protege) * [Integrations overview](/integrations) * [Troubleshooting](/event-feed/troubleshooting) # Integrations ## What this is This section explains how Hookshot™ connections work and how to reason about integration setup. ## When to use it Use this section when you are connecting an app for the first time or repairing one that is no longer ready. ## What you need first * Permission to manage integrations in your workspace * Access to the external app you want to connect ## Steps ### 1. Understand the two kinds of access * **Trigger Access**: what can start a Protege * **Tool Access**: what a Protege can do after it starts Some integrations support both. Others may be used primarily as a source, destination, or chat surface. {% hint style="info" %} Additional integrations beyond those listed below are available in the integration catalog. If you need a service not covered by a dedicated page, check the catalog to see if it is already supported. {% endhint %} {% hint style="info" %} Some integration capabilities appear in the UI but are not covered by a dedicated documentation page. If you cannot find a feature here, contact Protege AI support for help. {% endhint %} ### 2. Review the integration lifecycle ![Connect Slack in Integrations](/files/WLIgubDI5cSTJYozeTOG) 1. Open the integration 2. Choose the right connection scope 3. Review Trigger Access 4. Review Tool Access 5. Repair or reconnect anything marked degraded 6. Verify the setup with a real event or schedule ### 3. Choose the right connection scope Use the smallest connection scope that supports the workflow. * **Team connections** are shared by the team and fit most production Proteges. * **Personal connections** are tied to one user and should be used only when the workflow needs that user's account context. * **Chat connections** are managed at the team level for supported chat surfaces. #### Team connections A team connection uses a shared credential that belongs to the entire team. It is the right choice for: * Production Proteges that run unattended * Workflows where the action should come from the team identity, not an individual * Any scheduled Protege that runs without a specific user present Team connections: * Survive when team members leave the workspace * Can be managed by workspace admins and users with config write access * Are available to Proteges running in any mode (attended or unattended) #### Personal connections A personal connection uses a credential tied to one specific workspace user. It is the right choice for: * Workflows that need to act as a specific person (for example, creating a task assigned to that person) * Proteges that read from or write to resources only that user has access to Personal connections: * Require the owning user to remain an active workspace member * Become orphaned if the user leaves the workspace — the credential remains but cannot be resolved for any active user * Are managed by the individual user who connected them {% hint style="warning" %} If the user who owns a personal connection leaves the workspace, any Protege relying on that connection will fail for unattended runs. Use team connections for production workflows that must survive team changes. {% endhint %} #### Selected and default connections When a toolkit has both team and personal connections, Hookshot uses the **selected connection** — the one marked as the active credential for the team. For personal connections used in unattended runs, Hookshot uses the **default personal connection** — the one marked as the default for the team. This ensures scheduled Proteges have a predictable credential even when no user is present. You can see which connection is selected and which is default in the integration detail view. #### Chat connections Chat connections are always team-scoped. When you enable chat on an integration, the chat credential is managed at the team level. This is required because chat responses can be triggered at any time, including when no specific user is online. See [Chat](/create-a-protege/chat) for more on chat configuration. #### Auth expiry and reconnection When a connection expires or is revoked by the provider: * **Personal scope**: An email is sent to the user who owns the connection with a reconnect link * **Team scope**: An email is sent to team leads and admins with a reconnect link * The integration detail view shows the expired status and a reconnect option ### 4. Use a consistent verification loop For every integration: * Confirm the connection is active * Confirm the right trigger source is live * Confirm the right tools are available * Confirm chat configuration is complete if the integration receives chat activity * Confirm Event Feed receives the event * Confirm Audit shows the run {% hint style="info" %} The safest way to verify an integration is end-to-end. A healthy connection screen alone does not prove that the event path and action path are both working. {% endhint %} ## How to verify You are ready to move on when you can answer: * What will start this Protege? * What will this Protege do with the integration? * Which connection scope owns the workflow? * Where will I verify that behavior? ## Common failures * Approving the connection but not checking trigger scope * Using the wrong connected account or workspace * Assuming one integration connection covers every team or project boundary * Repairing Tool Access but forgetting Trigger Access, or the reverse ## Next step * [Slack](/integrations/slack) * [GitHub](/integrations/github) * [Asana](/integrations/asana) * [Jira](/integrations/jira) # Slack ## What this is Slack is a Hookshot™ integration that connects your Slack workspace to Hookshot. Slack commonly serves as a destination for notifications and summaries, a source of event-driven activity, and a chat surface where Proteges can respond to messages. ## When to use it * When a Protege should post messages or summaries to Slack * When Slack activity should start a Protege * When you want to talk to a Protege inside a Slack thread by mentioning `@hookshot` ## What you need first * Access to the Slack workspace you want to connect * Permission to approve the Hookshot connection flow * A clear channel or audience boundary for the workflow ## Steps ### 1. Connect Slack 1. Open **Integrations**. 2. Select **Slack**. 3. Complete the connection flow. 4. Confirm the integration shows as connected. ### 2. Review Trigger Access Use Trigger Access when Slack should start the Protege. Examples: * A channel-specific event * A Slack activity pattern your workspace wants to monitor Confirm the correct trigger source is live and mapped to the intended channel boundary. ### 3. Review Tool Access Use Tool Access when the Protege should do something in Slack. Examples: * Send a message * Send a summary * Deliver a reminder to a chosen destination {% hint style="warning" %} Tool Access deserves extra review for Proteges that post messages. Grant only the posting actions the workflow needs, and confirm the destination channel is correct. {% endhint %} ### 4. Set up chat Slack chat is team-scoped. When you enable chat on Slack, Hookshot can respond to direct mentions in channels where the Slack bot is present: * Mention `@hookshot`, `@hookshotdev`, or `@composio` to invoke a response * Hookshot replies in the same Slack thread as the mention * While processing, an `:eyes:` emoji reaction appears on the triggering message * Follow-up messages in the same thread continue the conversation without needing another mention Chat connections are always team-scoped — they cannot be personal connections. See [Chat](/create-a-protege/chat) for the full chat feature documentation. ### 5. Review permissions Review the Slack consent screen carefully. In practice, Hookshot needs permission to: * Observe the Slack activity that should start the workflow * Post or update the Slack output your Protege is expected to produce If you approve too little, the connection may look healthy while the Protege still cannot start or act correctly. ## How to verify * Confirm Slack is connected in Integrations * Confirm the intended Slack trigger source is live, if Slack starts the workflow * Confirm Tool Access covers the posting behavior you expect * Confirm chat configuration is enabled if Slack messages should start the workflow * Confirm Event Feed shows the Slack-related event or downstream activity * Confirm Audit shows the run and outcome ## Common failures * Connecting the wrong Slack workspace * Posting into the wrong channel boundary * Assuming any Slack connection can post everywhere you care about * Debugging only in Slack instead of checking Event Feed first * Enabling chat but not confirming the chat connection is active * Expecting Hookshot to respond without an explicit `@hookshot` mention * Using a personal connection instead of a team connection for chat ## Next step * [GitHub](/integrations/github) * [Integrations Overview](/integrations) * [Chat](/create-a-protege/chat) * [Event Feed](/event-feed) # GitHub ## What this is GitHub is a Hookshot™ integration that connects your GitHub organization or repository to Hookshot. GitHub commonly serves as a source of issue and repository activity and as a workflow input for triage, routing, and review. ## When to use it * When GitHub events should start a Protege * When a Protege needs to read GitHub context or take an action tied to GitHub data * When you want to triage, route, or review GitHub issues and pull requests automatically ## What you need first * Access to the GitHub organization, repository, or account you want to connect * Permission to approve the connection * A clear repo or project boundary for the automation ## Steps ### 1. Connect GitHub 1. Open **Integrations**. 2. Select **GitHub**. 3. Complete the connection flow. 4. Confirm the connection is active. ### 2. Review Trigger Access Use Trigger Access when GitHub events should start the Protege. Examples: * New issue activity * Selected repository events Confirm the trigger source points to the intended repo or project boundary. ### 3. Review Tool Access Use Tool Access when the Protege should read GitHub context or take an action tied to GitHub data or results derived from it. Examples: * Read issue context * Read pull request context * Support triage or routing workflows * Feed a downstream action in another system If the Protege should only operate on one repo, keep the connection boundary as narrow as possible. ### 4. Review permissions Review the GitHub consent screen and allow only what your workflow needs. In practice, Hookshot™ needs permission to: * Read the GitHub objects that should activate the workflow * Access enough repository context for the Protege to make the intended decision If the Protege should only operate on one repo or one team workflow, keep the connection boundary as narrow as possible. ## How to verify * Confirm GitHub is connected * Confirm the intended trigger source is live * Trigger a safe test event in the intended repo boundary * Confirm the event appears in Event Feed * Confirm the corresponding run appears in Audit ## Common failures * Connecting the wrong repo or account * Treating a repo-level workflow like an org-wide workflow * Forgetting to validate the exact event type that should activate the Protege * Event Feed shows the event but the Protege is `skipped` — review the Protege description and readiness ## Next step * [Asana](/integrations/asana) * [Integrations Overview](/integrations) * [Event Feed](/event-feed) # Asana ## What this is Asana is a Hookshot™ integration that connects your Asana workspace to Hookshot. Asana commonly serves as a source of tasks or project status, a scheduled review target, and a data source for workflow checks. Asana also provides a chat surface where Proteges can respond to task comments. ## When to use it * When Asana activity should start a Protege * When a Protege should inspect Asana state before acting * When you want to talk to a Protege inside an Asana task comment by mentioning `@hookshot` * When you need to sync Asana projects into the Work Hub ## What you need first * Access to the Asana workspace, project, or task area you want to use * Permission to complete the connection flow * A clear reminder or review workflow ## Steps ### 1. Connect Asana 1. Open **Integrations**. 2. Select **Asana**. 3. Complete the connection flow. 4. Confirm the integration is connected. ### 2. Review Trigger Access Use Trigger Access when Asana activity should start the Protege. Examples: * A task created or updated in a selected project * A live event path scoped to a project or portfolio Configure the trigger to the narrowest project or portfolio boundary. If an Asana project is already managed by a Work Hub project, the Builder presents the Work Hub project as the scope instead of raw Asana triggers. The Work Hub provider sync automatically sets up and maintains the trigger subscription for the linked project. ### 3. Review Tool Access Use Tool Access when the Protege should inspect Asana state before acting. Examples: * Check whether a task is complete * Review project state before sending a reminder * Update or respond to Asana work when the workflow allows it If an Asana project is managed by a Work Hub project, Work Hub policy mediates writes. The Protege cannot directly write to Asana for managed sources. Use the smallest practical project or workspace scope for the job. ### 4. Set up Work Hub provider sync You can link an Asana source to a Work Hub project so that Hookshot imports and tracks Asana tasks. 1. In Work Hub, choose **Create a project**. 2. Select the **Asana** option. 3. Select an Asana connection (or connect one first if none exists). 4. Browse and select an Asana source: a **project**, **portfolio**, or **workstream**. 5. Configure the project details. 6. Confirm — Hookshot imports all tasks, comments, attachments, and project links from the selected source and automatically creates a provider-managed trigger subscription. {% hint style="info" %} Asana provider sync supports both import and outbound projection. Changes you make in Work Hub can push back to Asana. Hookshot periodically reconciles data to catch changes that event listeners missed. {% endhint %} #### What gets imported | Asana concept | Work Hub concept | | -------------------------- | -------------------------------------------------------- | | Asana project or portfolio | Project with imported workstream | | Asana task | Work item with status, priority, assignee, custom fields | | Asana comments | Comments | | Asana attachments | Artifacts | ### 5. Set up chat Asana chat is team-scoped. When you enable chat on Asana, Hookshot can respond to mentions in task comments: * Include `@hookshot`, `@hookshotdev`, or `@composio` in a task comment to invoke a response * Hookshot posts its reply as a comment on the same task * While processing, a temporary "Hookshot is working on this..." comment appears and is automatically deleted after the response is posted * Follow-up comments in the same task continue the conversation Chat connections are always team-scoped — they cannot be personal connections. See [Chat](/create-a-protege/chat) for the full chat feature documentation. For Asana chat-style workflows, choose the exact projects or portfolios Hookshot should monitor. A Protege should not watch a broader Asana area than the workflow owner can review. ### 6. Review permissions Review the Asana connection carefully. In practice, Hookshot™ needs permission to: * Access the tasks or project objects that matter for your workflow * Read enough context to decide whether a reminder or follow-up is necessary Use the smallest practical project or workspace scope for the job. ## How to verify * Confirm Asana is connected * Confirm the relevant trigger source or scheduled workflow is ready * Confirm any managed project or portfolio selection is correct * If using Work Hub, confirm the imported work items match the Asana source * Use a known incomplete or known test item * Check Event Feed for the scheduled or live activity * Check Audit for the resulting reminder or follow-up run ## Common failures * Running a reminder workflow against the wrong project * Forgetting to verify the exact task or project boundary * Treating a scheduled review as verified before a real scheduled test occurs * The Protege runs but reminds on the wrong work — narrow the project or task boundary * Using a personal connection instead of a team connection for chat * Approving an outbound write in Work Hub without checking it will push back to Asana * Selecting a trigger without finishing trigger setup: Asana triggers require a project or portfolio to be selected before the Protege can be enabled ## Next step * [Jira](/integrations/jira) * [Integrations Overview](/integrations) * [Chat](/create-a-protege/chat) * [Work Hub](/event-feed/work-hub) # Jira ## What this is Jira is a Hookshot™ integration that connects your Atlassian Jira instance to Hookshot. It enables three capabilities: * **Trigger Access**: Proteges can start runs in response to Jira events such as issue creation or status updates. * **Tool Access**: Proteges can use the full Jira API through Hookshot to create issues, update issues, add comments, and manage transitions. * **Work Hub Provider Sync**: You can link a Jira project, Jira Service Management (JSM) queue, or request type to a Work Hub project, importing issues as work items with full field mapping. Jira does not support chat. ## When to use it * When Jira events should start a Protege * When a Protege should create or update Jira issues as part of an automated workflow * When you want to mirror a Jira project into Work Hub so Hookshot becomes the control plane for triage, decisions, and follow-up work ## What you need first * Access to the Jira instance you want to connect * Permission to complete the connection flow * A clear project, queue, or request type boundary for the automation ## Steps ### 1. Connect Jira 1. Open **Integrations**. 2. Find **Jira** in the integration catalog. 3. Choose **Connect** and complete the connection flow. 4. Authenticate with your Jira instance and grant the requested permissions. 5. Confirm the integration shows as connected. {% hint style="info" %} If your Jira instance uses custom authentication, contact Protege AI support for setup assistance. {% endhint %} ### 2. Review Trigger Access Use Trigger Access when Jira events should start the Protege. Examples: * A new issue created in a selected project * An issue updated or transitioned Configure the trigger to the narrowest project or queue boundary. Available inputs include project ID and project key. If a Jira project is already managed by a Work Hub project, the Builder presents the Work Hub project as the scope instead of raw Jira triggers. ### 3. Review Tool Access Use Tool Access when the Protege should take actions in Jira. Examples: * Create a new issue * Update an existing issue * Add a comment * Manage status transitions If a Jira project is managed by a Work Hub project, Work Hub policy mediates writes. The Protege cannot directly write to Jira for managed sources. ### 4. Set up Work Hub provider sync You can link a Jira source to a Work Hub project so that Hookshot imports and tracks Jira issues. 1. In Work Hub, choose **Create a project**. 2. Select the **Jira** option. 3. Select a Jira connection (or connect one first if none exists). 4. Browse and select a Jira source: a **project**, **JSM queue**, or **request type**. JSM stands for Jira Service Management. A JSM queue is a service desk queue that groups customer requests by category. 5. Configure the project details. 6. Confirm — Hookshot imports all issues, comments, attachments, approvals, and issue links from the selected source. {% hint style="info" %} Jira provider sync uses periodic polling and reconciliation to import data into Work Hub. It does not push changes back to Jira — changes you make in Work Hub stay in Work Hub. Because Jira does not support managed event listeners, data updates appear after the next reconcile cycle rather than in real time. {% endhint %} #### What gets imported | Jira concept | Work Hub concept | | ------------------------------------ | -------------------------------------------------------- | | Jira project, queue, or request type | Project with imported workstream | | Jira issue | Work item with status, priority, assignee, custom fields | | Jira comments | Comments | | Jira approvals | Decisions | | Jira attachments and remote links | Artifacts | | Jira parent/epic links | Relationships | ### 5. Review permissions Review the Jira consent screen and allow only what your workflow needs. Hookshot™ needs permission to: * Observe the Jira items that should start the workflow * Access enough issue context to support the intended action * Read and write issues if the Protege will create or update them Keep the scope limited to the relevant project whenever possible. ## How to verify * Confirm Jira is connected in Integrations * Confirm the intended trigger source is live * Create a safe test issue in the selected project * Check Event Feed for the incoming activity * Check Audit for the resulting run * If using Work Hub, confirm the imported work items match the Jira source ## Common failures * "No Jira account" appears in Work Hub — connect Jira in Integrations first, then return to Work Hub * "Reconnect Jira account" appears — the connection has expired or been revoked. Reconnect in Integrations. * Events never arrive in Event Feed — confirm the trigger source is enabled and the project boundary is correct * Work Hub project shows no imported items — confirm the Jira connection was fully finalized after the initial connection * Status changes do not push back to Jira — this is expected. Jira outbound projection is not supported. Changes stay in Work Hub. ## Next step * [Asana](/integrations/asana) * [Integrations Overview](/integrations) * [Work Hub](/event-feed/work-hub) * [Event Feed](/event-feed) # Operate ## What this is The Event Feed is the fastest place to confirm whether Hookshot™ saw an incoming event and how Proteges responded to it. ## When to use it Use Event Feed when: * You are testing a new Protege * You suspect a trigger is not firing * You need to know whether Hookshot saw the event at all ## What you need first * A connected integration or schedule * A Protege expected to respond to an event ## Steps ### 1. Look for the event ![Event Feed with a first event](/files/S1fc15keJmmrwMN3eA4e) Find the incoming task you expected from the provider. The feed can include external app events, scheduled activity, and run-related entries. Start by confirming the source, timestamp, and any linked Protege. ### 2. Check the Protege status You may see: * `ran` * `running` * `dispatching` * `skipped` * `unevaluated` ### 3. Use the status as a next action * If you see `ran`, move to Audit to inspect the actual run result. * If you see `running`, the Protege is executing. Wait for it to finish and then refresh. * If you see `dispatching`, give the workflow a moment and then recheck. * If you see `skipped`, review whether the Protege should have acted on that event. * If you see `unevaluated`, review whether the event path and setup are complete. ### 4. Open related runs When a feed item has a related run, use it to jump into Audit. Event Feed tells you whether Hookshot saw and routed the signal; Audit tells you what happened during execution. {% hint style="info" %} If you see `ran`, it means Hookshot executed the Protege. Do `Audit` next to inspect the result. {% endhint %} {% hint style="warning" %} If you see `skipped`, it means Hookshot saw the event but chose not to run the Protege. Do `review trigger setup and Protege logic` next. {% endhint %} ## How to verify ### You’re done when... * The expected event appears * The expected Protege is associated with it * You understand which next step belongs to the status you see * Any related run can be opened in Audit ## Common failures * No event appears at all * The wrong Protege is associated with the event * The same event path is too noisy * A user jumps to Audit before confirming the event arrived * A scheduled workflow is checked before the schedule has actually fired ## Next step * [Audit](/event-feed/audit) * [Work Hub](/event-feed/work-hub) * [Troubleshooting](/event-feed/troubleshooting) # Audit ## What this is Audit is the place to verify run history and understand what happened after a Protege executed in Hookshot™. Audit includes fleet-wide runs, Protege-specific history, run detail timelines, tool usage, logs, feedback, and analytics. ## When to use it Use Audit when: * Event Feed shows `ran` * You need to review outcomes * You need to explain or share what the Protege did * You want to teach a Protege by providing feedback on a run ## What you need first * A Protege that has already been triggered ## Views ### Fleet runs The main Audit view shows recent runs across all Proteges. Use it when you are comparing runs or reviewing overall workspace activity. Summary metrics at the top show: * **Runs in view**: Total filtered runs * **Orchestration OK**: Percentage of runs that finished without executor error * **Failed outcomes**: Count of business-reported failures * **Reviewed**: Count of runs marked as reviewed Filter by Protege, search across run details, or narrow the time range. ### Protege index The Protege index shows all Proteges with their audit history at a glance. Search by name, filter by status, or narrow the date range to find a specific Protege. From the index, select a Protege to open its detailed aggregate view. ### Protege-specific audit From the Protege aggregate view, you can inspect one Protege's history including: * **Summary metrics**: Total runs, success rate, action rate, average duration, credits consumed * **Outcomes**: Status breakdown (success vs failure) * **Decision mix**: How often the Protege decided to run vs not run * **Top triggers**: Most common event sources * **Tool usage**: Per-tool call counts, failure rates, and read/write classification * **Recent runs**: Recent runs with trigger, duration, and output summary ### Should-I-Run Review The decisions view shows every dispatch evaluation as a first-class audit record, grouped by trigger event. For each event, you can see which Proteges evaluated it, whether they decided to run or not, the confidence level, and the reason for the decision. Use this view when: * A Protege is being skipped and you want to understand why * You want to review whether the dispatch confidence is appropriate * You need to trace a decision back to its trigger event ### Analytics The analytics view shows aggregated trends: * **Run outcomes**: Status distribution (success, failure, dead letter) with percentages * **Decision summary**: Run vs did-not-run counts over time * **Tool usage across runs**: Which tools are used most, classified as read or write, with failure correlation ## Steps ### 1. Find the relevant run Start from the Protege or from Event Feed and open the run you want to inspect. Use the fleet view when you are comparing runs across Proteges. Use Protege audit when you are focused on one automation. ### 2. Review the outcome Look for: * Whether the run completed as expected * Whether the output matches the intended workflow * Whether the run result is clear enough for another teammate to review * Whether the run performed an external action or only read information * Which tools were used and whether logs explain the result ### 3. Inspect a single run ![Audit run detail](/files/F62Bsfp6tktMEx2d0I8u) Open a run to see five tabs: | Tab | What it shows | | ------------------ | ----------------------------------------------------------------------------------------- | | **Overview** | Decision assessment, operator review, pending writes, tool usage summary | | **Events** | Unified timeline with filters: all, actions, reads, issues, background | | **Input & Output** | Input event payload and run output as JSON | | **Session Log** | Log Stream sub-tab for recent entries, or Full Session Export for the complete transcript | | **Teach** | Operator feedback form | ### 4. Teach your Protege The **Teach** tab lets you provide feedback on a run: * **Should this Protege have run?**: Yes, No, or Unclear * **Guidance**: Free-text instructions that help the Protege make better decisions in the future Teaching notes are stored permanently on the run and contribute to the Protege's ongoing behavior calibration. ### 5. Use Audit as your proof point Audit is the best place to answer: * What happened? * Which Protege ran? * What was the result? * What action did it take? * Was the action a read or a write? {% hint style="info" %} If you see the expected run in Audit, it means Hookshot™ moved beyond event intake and executed a workflow you can inspect. {% endhint %} ## Tool classification Every tool call in Audit is classified as **Read** or **Write**: * **Read** operations access or retrieve information without changing external state * **Write** operations create, update, or delete information in external systems Classification is sourced from the integration catalog when available. Use this classification to quickly assess whether a Protege only read context or also made changes. ## How to verify ### You're done when... * You can locate the run * You can describe the run outcome in one sentence * The outcome matches the event you saw in Event Feed * The action label and tool usage match what the Protege actually did * You have provided teaching notes for any run where the behavior was unexpected ## Common failures * Searching Audit before confirming the event exists in Event Feed * Reviewing the wrong run after testing several events * Seeing a run but not checking whether it was scoped correctly * Treating a `No Action` run as a failure when the Protege intentionally read context without writing to another system * Skipping the Teach tab when the Protege made an incorrect decision ## Next step * [Event Feed](/event-feed) * [Troubleshooting](/event-feed/troubleshooting) * [Work Hub](/event-feed/work-hub) # Work Hub ## What this is The Work Hub is the Hookshot™ operations center for managing tasks, decisions, agent-authored changes, and provider sync. It brings together the work that Proteges do with the human review and approval workflows that keep it safe. ## When to use it Use the Work Hub when you need to: * Review and approve or reject changes that a Protege wants to make * Browse tasks across projects and workstreams * Track decisions, context, and activity on tasks * Manage provider sync with Asana or Jira ## What you need first * A workspace with at least one Protege that writes to the Work Hub * Permission to access the Work Hub view ## Steps ### 1. Understand key concepts #### Workstreams and Imported Workstreams Workstreams are named groups that organize projects within the Projects view. An imported workstream is a group of projects synced from an external provider such as Asana or Jira. #### Projects A project is a named set of tasks. Each project has: * A default priority * Optional custom field definitions * Optional completion rules that determine when a task is done * Provider sync tracking (import, outbound sync, drift reconciliation status) #### Tasks A task has standard fields: title, description, status, priority, assignee, and requester. Tasks can also carry custom field values, source attachments (with preview states), source links to external resources, and references to the Protege runs that created or modified them. #### Decisions A decision is an approval or recommendation attached to a task. Proteges can request decisions when they encounter something that needs human judgment. Each decision has a type, status, recommendation, and rationale. #### Artifacts Artifacts are notes, attachments, and links that provide background for tasks. They help Proteges make better decisions by giving them access to relevant reference material. #### Comments Comments on tasks can be: * **Local only**: Created and managed entirely in Hookshot * **Provider imported**: Synced from an external provider (Asana, Jira) * **Provider synced**: Written in Hookshot and pushed to the external provider ### 2. Understand completion rules Projects can use one of three completion modes: | Rule | How a task is completed | | ---------------------------- | ----------------------------------------------------------------------- | | **Explicit completion** | A human manually changes the task status | | **Provider task completion** | Automatically completed when the linked Asana or Jira task is completed | | **Custom field option** | Completed when a specific enum custom field is set to a specific option | Custom field option completion supports a reopen behavior: either clear the field or set it to a different option. #### Provider task completion behaviors When a queue is linked to an external provider, the **Provider task completion** mode controls how completing or reopening an item syncs back to the provider. **Asana behaviors** (set in queue settings under "Provider completion behavior"): | Behavior | What happens when an item is completed | | ------------------ | ------------------------------------------------------------------ | | **Completed flag** | Marks the Asana task as completed | | **Custom field** | Sets a specific custom field option to mark completion | | **Both** | Marks the Asana task as completed AND sets the custom field option | When using custom field or both, you choose which enum field and which option represents "done." Reopen behavior can either clear the field value or set it to a different option. **Jira behaviors** (set in queue settings under "Provider completion behavior"): | Setting | What it does | | ------------------- | ------------------------------------------------------------------ | | **Complete status** | The Jira status name to transition to when completing (e.g., Done) | | **Reopen status** | The Jira status name to transition to when reopening (e.g., To Do) | #### Provider-native status display By default, work item statuses are normalized to the local Work Hub status set (open, review, blocked, done, etc.). You can switch a queue to **provider-native statuses** to display the provider's own status names instead — for example, showing "In Progress" or "Ready for QA" from Asana, or "In Review" from Jira. This setting is configured per queue under **Status display mode** in queue settings. ### 3. Set up provider sync The Work Hub supports sync with external providers (Asana and Jira): * **Import**: Pull records from the external provider into Work Hub projects * **Outbound sync**: Push changes from Work Hub back to the external provider (create tasks, update fields, post comments). Asana supports outbound sync. Jira does not. * **Event coverage**: Asana supports managed event listeners that receive real-time updates. Jira does not have managed event listeners — it relies on periodic polling instead. * **Drift reconciliation**: A periodic full sync (every 24 hours) catches changes that real-time listeners or polling may have missed {% hint style="info" %} Provider sync status is tracked per project. You can see import, outbound sync, and drift reconciliation status on each project's detail view. {% endhint %} ### 4. Configure the write policy The write policy controls whether Protege operations go through directly or require human approval before they are applied. #### Policy sources Four sources contribute to the final policy decision: | Source | Scope | | -------------------- | --------------------------------------------------------------------- | | **Work Hub default** | Global default for all projects (`autonomous` or `approval_required`) | | **Project policy** | Per-project override from the project's SLA policy | | **Protege policy** | Per-Protege write policy from its access configuration | | **Sensitivity** | Based on the operation type | If **any** source says `approval_required`, the result is `approval_required`. #### Operations that always require approval Some operations always require human review regardless of policy settings: * Approval-sensitive work (operations that affect visible output) * Decision approval (when a Protege requests a decision) * Provider sync (writes that will push to an external provider like Asana or Jira) #### Autonomous mode In `autonomous` mode, the Protege's changes are applied immediately and appear in the task right away. Use autonomous mode for low-risk operations in trusted workflows. #### Approval required mode In `approval_required` mode, the Protege's changes create a **Pending Write** that waits for a human to approve or reject it before it is applied. See [Pending Writes](/event-feed/pending-writes) for the full review workflow. ### 5. Configure Work Hub settings Work Hub defaults are configured per team at **Settings → Work Hub**: * **Write policy**: Default for all projects (autonomous or approval\_required) * **Outbound default**: How outbound writes behave * **Comment default**: Default comment sync mode * **Product label**: Display label for the Work Hub instance ### 6. Navigate Work Hub views The Work Hub offers several views: | View | Purpose | | ------------- | ------------------------------------------------------------------------------------------------------------- | | **Inbox** | Attention items, pending decisions, and recent activity. This is the default view when you open the Work Hub. | | **Projects** | Browse projects and workstreams with sync status | | **Work** | Task list within a selected project | | **Decisions** | Decision list with pending write review | | **Artifacts** | Artifact browser with attachment preview | You can filter tasks using the multi-field filter bar. Active filters appear as removable chips. ## How to verify * Projects show the expected tasks from providers * Pending writes appear for approval when Proteges make changes under approval-required policy * Approved writes are applied to tasks and projected to external providers where configured * Drift reconciliation runs periodically and reports sync status per project ## Common failures * Enabling autonomous mode for a project that handles sensitive external writes * Approving a pending write without reviewing the before/after snapshots * Importing from a provider without confirming the correct project or portfolio scope * Ignoring drift reconciliation errors on projects that depend on provider sync * Assuming a completed task in Work Hub means the provider task is also completed ## Next step * [Pending Writes](/event-feed/pending-writes) * [Audit](/event-feed/audit) * [Event Feed](/event-feed) # Pending Writes ## What this is A Pending Write is a Protege-authored change that is waiting for human review before it is applied in Hookshot™. Pending writes are created when the write policy for a project or Protege requires approval. ## When to use it Use this page when you need to: * Review changes a Protege wants to make * Approve, reject, or edit a pending change * Understand what happens when a pending write goes stale ## What you need first * A workspace with Proteges that write to the Work Hub under an approval-required policy * Permission to review pending writes (workspace owner, admin, or team lead) ## Steps ### 1. Find pending writes Open **Work Hub** → **Decisions** to see pending writes awaiting review. Each pending write shows: * The Protege that authored it * The target task and project * The operation type (create, update, comment, etc.) * Whether the write will sync to an external provider (Asana or Jira) * The policy reasons why approval was required ### 2. Review the change Open a pending write to see: * **Before snapshot**: The current state of the task before the change * **After snapshot**: What the task will look like if the change is applied * **Edited payload**: If you modify the change before approving, the edited version appears here {% hint style="warning" %} Always review both the before and after snapshots before approving. The Protege may have made assumptions about the current state that are no longer accurate. {% endhint %} ### 3. Approve, reject, or edit | Action | What happens | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Approve** | The change is applied to the task. If the project has provider sync enabled, the change is also pushed to the external provider. | | **Reject** | The change is discarded. You can optionally provide a reason. | | **Edit then approve** | You modify the payload before approval. The edited version is applied instead of the original. | ### 4. Handle stale writes A pending write becomes **stale** if the underlying task has changed since the write was created. Stale writes are flagged because the before snapshot no longer matches the current state of the task. When you encounter a stale write: * Review whether the change is still appropriate given the new task state * If it is still valid, approve it (the system will apply it against the current state) * If it is no longer valid, reject it ### 5. Reopen a rejected write If you rejected a write by mistake, you can **reopen** it for re-review. The write returns to `pending` status and can be approved or rejected again. ### 6. Understand write policy and pending writes Pending writes are created when the write policy evaluates to `approval_required`. The policy is determined by four sources: 1. **Work Hub default** — the global setting 2. **Project policy** — per-project override 3. **Protege policy** — per-Protege setting 4. **Sensitivity** — the operation type If any source says `approval_required`, a pending write is created instead of applying the change directly. Operations that always require approval: * Approval-sensitive work * Decision requests * Provider sync (writes that will push to Asana or Jira) ### 7. Review provider impact When a pending write targets a project that has provider sync enabled, approving the write will also push the change to the external provider. The pending write view shows whether the write has provider impact so you can consider the external consequences before approving. ## How to verify * Pending writes appear for Protege changes that require approval * Approved writes are applied to tasks and reflected in the task detail view * Rejected writes are discarded and not applied * Stale writes are flagged with a clear indicator * Provider-synced writes update the external provider after approval ## Common failures * Approving a write without checking the after snapshot * Ignoring stale indicators when the task has changed * Approving a provider-projected write without considering the external impact * Rejecting a valid write that could have been edited instead * Assuming direct mode is safe for all projects without reviewing the operations ## Next step * [Work Hub](/event-feed/work-hub) * [Audit](/event-feed/audit) # Troubleshooting ## What this is This page helps you debug Hookshot™ by symptom, starting with the fastest checks. ## When to use it Use it whenever a Protege does not run, runs unexpectedly, or produces the wrong outcome. ## Symptom ### My Protege never runs #### Fastest checks * Confirm the source event appears in Event Feed * Confirm the integration is connected * Confirm Trigger Access is ready #### Likely causes * No event reached Hookshot * Wrong trigger source * Wrong connection scope #### Where to look in Event Feed Look for whether the event appears at all and whether any Protege was associated with it. #### Where to look in Audit If no run exists, the issue is likely earlier in the path than Audit. #### How to fix Reconnect or repair the integration, confirm the live source, and retest with a known-safe event. ## Symptom ### The event appears, but the Protege is skipped #### Fastest checks * Review the Protege description * Review readiness blockers * Confirm the event should really match the workflow #### Likely causes * The Protege is too narrow * The wrong trigger path is connected * Required access is incomplete #### Where to look in Event Feed Inspect the event entry and the associated Protege status. #### Where to look in Audit A skipped event may not produce the run result you expected, so Event Feed is the faster signal here. #### How to fix Tighten or clarify the Protege description, then verify the trigger source and required access. ## Symptom ### It says dispatching for too long #### Fastest checks * Refresh Event Feed after a short wait * Check whether Audit shows a corresponding run #### Likely causes * The event is still processing * The integration or workflow path needs attention #### Where to look in Event Feed Check whether the item progresses to a final status. #### Where to look in Audit Look for a matching run for the same Protege. #### How to fix If the state does not settle, review the integration health, recent setup changes, and rerun a controlled test. ## Symptom ### The Protege ran, but the result is wrong #### Fastest checks * Review the Protege description * Confirm the destination boundary * Confirm Tool Access covers the intended action path #### Likely causes * The Protege is too broad * The wrong destination or scope is configured * The workflow needs clearer constraints #### Where to look in Event Feed Confirm the correct source event triggered the run. #### Where to look in Audit Inspect the run outcome and compare it to the expected result. #### How to fix Narrow the scope, add stronger constraints, and retest with a safe event. ## Symptom ### Setup says a trigger is waiting for the first event #### Fastest checks * Confirm the integration is connected * Confirm the trigger source is registered * Send one known-safe event from the external app #### Likely causes * The trigger source has not received its first matching event * The selected project, repo, channel, team, or portfolio is not the one being tested * The integration was connected but trigger setup was not finished #### Where to look in Event Feed Look for the first event from the selected source. If no event appears, the issue is still in the source or trigger path. #### Where to look in Audit Audit will only help after Hookshot has routed the event into a run. #### How to fix Send a controlled event from the exact configured source. If nothing appears, review Trigger Access and reconnect or repair the integration. ## Still stuck? Email **** and the Protege AI team will help you debug the issue. ## Next step * [Event Feed](/event-feed) * [Audit](/event-feed/audit) * [Readiness and blockers](/create-a-protege/readiness-and-blockers) # Safe Rollout ## What this is This page describes how to launch or change a Protege with lower risk. ## When to use it Use it before enabling a new Protege, widening its scope, or changing its connected integrations. ## What you need first * A working Protege * Verified Event Feed and Audit behavior in at least one controlled test ## Steps ### 1. Start narrow * Use one project, repo, team, channel, or equivalent boundary * Avoid company-wide destinations for a first rollout ### 2. Test with real but safe traffic * Use one event path you understand * Confirm Event Feed first * Confirm Audit second ### 3. Prepare the stop path Know how to: * Disable the Protege * Pause the workflow if needed * Repair or disconnect a broken integration * Confirm whether removing integration permissions affects any live Proteges ### 4. Expand only after verification Expand scope only when: * The Protege behaves consistently * The owner understands the failure modes * The verification path is clear to the wider team * Billing and usage expectations are understood for the larger rollout {% hint style="info" %} Safe rollout is mostly about scope control, observability, and reliable rollback. Keep those three things simple before you broaden coverage. {% endhint %} ## How to verify ### You’re done when... * The Protege works inside a narrow boundary * Event Feed and Audit both confirm the intended behavior * The owner knows how to pause or disable the workflow ## Common failures * Turning on a broad workflow first * Using several integrations before validating one simple path * Expanding scope before a clean controlled test * Disconnecting or changing an integration without checking which Proteges depend on it ## Next step * [Security and permissions](/workspace-settings/security-and-permissions) * [Troubleshooting](/event-feed/troubleshooting) # Release Notes ## Highlights * **Step-by-step Protege creation wizard**: New Proteges are created from the Proteges screen using a four-step wizard. [Create a Protege](/create-a-protege) # April 2026 ## Highlights * **Customer docs launched**: Added the first GitBook documentation for getting started, integrations, operations, and admin workflows. [Start here](/) * **Protege Builder and drafts**: Added chat-based Protege creation with drafts, plan review, acceptance, and setup handoff. [Create a Protege](/create-a-protege) * **Faster Builder experience**: Improved catalog loading, plan rendering, and Builder responsiveness for large tool sets. [Create a Protege](/create-a-protege) * **Integration setup improvements**: Added richer integration catalog data, tool validation, trigger setup, and repair flows. [Integrations overview](/integrations) * **Team and personal connection scopes**: Separated team-scoped and user-scoped connections so access boundaries are clearer. [Security and permissions](/workspace-settings/security-and-permissions) * **Slack and Fathom setup improvements**: Improved Slack chat handling and added one-click Fathom trigger setup through Composio. [Slack](/integrations/slack) * **Asana trigger hardening**: Improved Asana trigger verification, handshake handling, and dispatch routing. [Asana](/integrations/asana) * **Event Feed visibility**: Added routing metrics, source filtering fixes, scheduling labels, and confidence details for ran events. [Event Feed](/event-feed) * **Audit timeline improvements**: Normalized tool events and improved run details, summaries, and analytics. [Audit](/event-feed/audit) * **Protege scheduling and subscriptions**: Improved event subscription behavior and schedule reconciliation for event-driven and scheduled runs. [Builder patterns](/create-a-protege/builder-patterns) * **Safer integration disconnects**: Proteges now protect against missing integration permissions by disabling or cleaning up affected paths. [Safe rollout](/event-feed/safe-rollout) * **Workspace access controls**: Added admin-only workspace management, credential visibility restrictions, SE access grants, and team controls. [Teams and people](/workspace-settings/teams-and-people) * **Billing and usage controls**: Added billing plans, credit packs, auto top-up alerts, usage states, and checkout improvements. [Workspace settings](/workspace-settings) # Admin ## What this is This page explains the customer-facing settings available in the workspace. ## When to use it Use it when you need to update profile information, review workspace retention behavior, or understand billing and usage settings. ## What you need first * Access to **Settings** ## Steps ### 1. Review profile details In workspace settings, you can review and update profile information such as: * Display name * First name * Last name * Nickname ### 2. Review Event Feed retention Hookshot™ exposes Event Feed retention choices in the workspace settings UI. Current available options: * 30 days * 60 days * 90 days ### 3. Confirm team expectations Before changing retention or profile settings, confirm: * Who relies on Event Feed history * Whether the current setting matches team expectations ### 4. Review billing and usage Depending on your workspace plan, Settings can include: * Current plan * Credit balance * Usage history * Payment activity * Credit packs * Auto top-up controls * Plan change or billing portal actions Use these views before broadening a Protege rollout, especially when a workflow may run frequently or use several tools. For a full explanation of credits, grants, auto top-up, and what happens when credits run out, see [Billing and Usage](/workspace-settings/billing). ## How to verify * Your profile changes appear in the UI * The retention setting reflects the option you selected * Billing and usage views match your expected plan and credit state ## Common failures * Changing retention without confirming team expectations * Assuming retention changes rewrite past investigative habits automatically * Expanding a high-volume Protege without reviewing usage expectations ## Next step * [Billing and Usage](/workspace-settings/billing) * [Teams and People](/workspace-settings/teams-and-people) * [Security and Permissions](/workspace-settings/security-and-permissions) * [Solutions Engineering Access](/workspace-settings/solutions-engineering-access) * [Environments and Sandbox](/workspace-settings/environments-and-sandbox) # Billing and Usage ## What this is This page explains how billing, credits, and usage tracking work in your Hookshot™ workspace. For current pricing and plan details, visit the [Protege AI website](https://protegeai.com). ## When to use it Use this page when you need to: * Understand how credits are consumed * Review your credit balance and usage history * Configure auto top-up * Purchase credit packs or change your plan ## What you need first * Workspace owner or admin role (for billing management) * Access to **Settings** ## Steps ### 1. Understand key concepts #### Credits Credits are the unit of consumption for Protege runs. Each time a Protege runs, the AI model usage (tokens in, tokens out, cached tokens) is converted into credits and deducted from your workspace balance. #### Credit grants Credits are added to your workspace through grants. Grant types include: | Type | How it works | | --------------------- | -------------------------------------------- | | **Included monthly** | Renewed with each subscription billing cycle | | **Trial credit** | Provided during a free trial period | | **Pack purchase** | One-time credit pack purchase | | **Bonus** | Added by Protege AI | | **Manual adjustment** | Admin adjustments | #### Credit consumption order When a Protege runs, credits are consumed from grants that expire soonest first. This ensures you use time-limited credits before they expire. #### Usage ledger Every billable event is recorded in the usage ledger with: * The source (dispatcher decision or Protege run) * The AI model used * Token counts (input, output, cached) * Credits charged Each billable event is recorded exactly once — you will never be charged twice for the same run. ### 2. Manage credits #### Credit balance View your current credit balance in **Settings → Plan**. The balance reflects all grants minus all consumptions. #### Credit packs Credit packs are one-time purchases that add credits to your balance. Packs do not expire, though the credits they provide are consumed in the standard depletion order alongside other grants. Visit the [Protege AI website](https://protegeai.com) for current pack options. #### Auto top-up Auto top-up automatically purchases a credit pack when your balance falls below a threshold you set. To configure auto top-up: 1. Go to **Settings → Plan** 2. Enable auto top-up 3. Choose the threshold (when to trigger a purchase) 4. Choose the pack size to purchase 5. Optionally set a monthly spending cap Auto top-up behavior: * Triggers when available credits fall at or below the threshold * Respects a monthly spending cap * Has a 6-hour cooldown after a failed purchase attempt * Sends an email notification if a purchase fails {% hint style="info" %} Auto top-up is not available for enterprise plans. Enterprise workspaces track overage separately and continue running even when the included credits are consumed. {% endhint %} #### Plan changes Plan changes are handled through the billing portal. Go to **Settings → Plan** to access it. Visit the [Protege AI website](https://protegeai.com) for plan comparison and upgrade options. ### 3. Understand what happens when credits run out | Plan type | Behavior | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **Self-serve** (Starter, Growth) | New Protege runs are blocked. Existing runs in progress will finish. A credit pack purchase or plan upgrade restores access. | | **Enterprise** | Runs continue. Overage is tracked separately and invoiced according to your enterprise agreement. | When credits run out on a self-serve plan, a reversal (debt) grant is created for each run that cannot be covered. Future credit pack purchases offset this debt before adding new available credits. ### 4. Review usage **Settings → Usage** shows: * Credit consumption over time * Per-run usage details with token counts and credits charged * Payment activity and billing history ### 5. Check seat limits Each plan includes a set number of team seats. When you invite a new member, Hookshot™ checks the seat count against your plan limit. If the limit is reached, you need to upgrade the plan or remove existing members before sending new invites. ## How to verify * Your credit balance reflects expected usage * Auto top-up triggers correctly when the threshold is reached * Usage history matches the Protege runs you observed in Audit * Plan changes take effect on the next billing cycle ## Common failures * Expanding a high-volume Protege without monitoring credit consumption * Disabling auto top-up and running out of credits unexpectedly * Assuming enterprise overage is free rather than tracked * Inviting team members without checking the seat limit * Purchasing a pack without confirming whether outstanding debt will be offset first ## Next step * [Workspace Settings](/workspace-settings) * [Teams and People](/workspace-settings/teams-and-people) # Teams and People ## What this is This page explains how to manage team spaces, workspace members, and invites in Hookshot™. ## When to use it Use it when onboarding teammates, changing team ownership, or reviewing access boundaries for Proteges. ## What you need first * Access to **Settings** * Permission to manage workspace membership ## Roles and permissions ### Workspace roles | Role | Who has it | What they can do | | ---------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | **Owner** | The person who created the workspace (set during bootstrap) | Everything an admin can do, plus manage billing and grant SE access | | **Admin** | Assigned by an owner when inviting | Manage teams, people, integrations, Protege configuration, workspace settings, SE access | | **Member** | Default role for new invites | View teams, integrations, Event Feed, Audit; create and edit Proteges within their teams | {% hint style="info" %} Owners and admins are treated equivalently for most workspace operations. The main difference is that owners are the initial workspace creators and have irrevocable access to billing. {% endhint %} ### Team roles | Role | What it means | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | | **Lead** | Accountable for the team. Leads appear in team membership lists and can review team-scoped changes. Initial owner is always a lead. | | **Admin** | Can manage team membership and settings (reserved for future use). | | **Member** | Standard team participant with access to team-scoped resources. | ## Steps ### 1. Manage teams From **Settings → Teams**, you can: * Review all teams * Add a team * Rename a team * Remove a team (except the default team) * Switch the active team context Every workspace has a **default team** (named "General" by default) that is created automatically when the workspace is bootstrapped. The default team cannot be deleted. #### Team scoping Resources in Hookshot™ are scoped to teams: * Proteges belong to a team * Skills belong to a team * Integrations and their credentials are scoped per team * Event Feed entries are associated with teams Switching your active team changes which resources you see. Always confirm you are in the correct team context before creating or editing resources. #### Removing a team When you remove a team: * All Proteges owned by that team are deleted (cascade) * All team memberships are removed * All integrations and feeds owned by that team are deleted * Pending invites targeting that team remain but lose their team assignment {% hint style="warning" %} Deleting a team is a destructive action. Review all Proteges, integrations, and pending writes owned by the team before proceeding. {% endhint %} ### 2. Manage people From **Settings → People**, you can: * Invite a person by email * Choose an initial team and workspace role (Member or Admin) * Review accepted members and their workspace role badges * Review pending invites with their target team and expiry * Update which teams a person belongs to #### Inviting a member 1. Enter the email address 2. Select the initial team 3. Choose the workspace role (Member or Admin) 4. Send the invite The invitee receives an invitation email. When they accept, they are automatically added to the workspace and the selected team with the specified roles. #### Seat limits Each plan includes a set number of team seats. Hookshot checks the seat count (accepted members + pending invites) before allowing new invites. If the limit is reached, you need to upgrade the plan or remove existing members before inviting new ones. See [Billing and Usage](/workspace-settings/billing) for more on plan limits. #### When a member leaves When a workspace member is removed or leaves: * Their team memberships are removed * Personal integration connections they owned become orphaned — the credential survives but can no longer be resolved for any active user * If they were the default personal connection for unattended runs, those runs will fail until another connection is configured * Team connections are unaffected * Proteges owned by their teams continue running normally {% hint style="warning" %} Before removing a member, review whether any Proteges rely on their personal connections. Replace personal connections with team connections for any production workflows before removing the member. {% endhint %} ### 3. Keep ownership clear For each live Protege, make sure: * A team owns it * The right people can review Audit and Event Feed * Changes are visible to the people responsible for support {% hint style="warning" %} Avoid orphaned automations. A Protege should always have a clear team boundary and at least one accountable owner. {% endhint %} ### 4. Active team switching Your active team determines which Proteges, skills, integrations, and events you see in the dashboard. Switch teams using the team selector in the navigation. Your active team is remembered across the session, so all resource queries are automatically scoped to the selected team. ### 5. Sandbox workspace restrictions Sandbox workspaces inherit team and people administration from their linked production workspace. In a sandbox: * You cannot invite new people * You cannot create, rename, or delete teams * Team membership is inherited from the production workspace * SE access must be provisioned separately — granting SE access in the production workspace does not grant it in the sandbox See [Environments and Sandbox](/workspace-settings/environments-and-sandbox) for the full environment documentation. ## How to verify * The intended teammate appears in the right team * Pending invites match your expectations * Team boundaries align with Protege ownership * The active team context matches the Proteges and integrations you are reviewing * Personal connections for departing members have been replaced with team connections ## Common failures * Inviting a user to the wrong team * Treating workspace access as the same thing as workflow ownership * Deleting or changing teams without reviewing Protege ownership * Editing team access while viewing the wrong active team * Relying on a personal connection for a production Protege * Not reviewing connection ownership before removing a team member ## Next step * [Environments and Sandbox](/workspace-settings/environments-and-sandbox) * [Workspace settings](/workspace-settings) * [Security and permissions](/workspace-settings/security-and-permissions) * [Billing and Usage](/workspace-settings/billing) # Security and Permissions ## What this is This page explains how to think about access, scope, and governance for Hookshot™ in a company setting. ## When to use it Use it when connecting apps, preparing for rollout, or reviewing risk with technical stakeholders. ## What you need first * A proposed workflow * At least one integration you plan to connect ## Steps ### 1. Use least privilege Connect only the integrations you need and keep the boundary as narrow as practical. Examples: * One team instead of every team * One repo instead of every repo * One channel instead of every channel ### 2. Separate trigger access from tool access Ask two different questions: * What should be allowed to start this Protege? * What should the Protege be allowed to do? Review both before launch. A healthy integration connection does not prove that the trigger path and action path are both correct. ### 3. Choose the right connection scope Use team-scoped connections for shared production workflows. Use personal connections only when the Protege needs one person's account context. For chat surfaces, confirm the team-level chat configuration and the exact channels, projects, or portfolios Hookshot should monitor. ### 4. Make ownership visible Before rollout, confirm: * Which team owns the Protege * Who can change integrations * Who is responsible for Audit review when something goes wrong ### 5. Pair security with observability The safer workflow is the one you can quickly inspect: * Event Feed shows the incoming signal * Audit shows the resulting action * Work Hub shows pending writes awaiting your approval {% hint style="info" %} For company automations, good governance means narrow scope, clear ownership, and a reliable rollback path more than maximum complexity in the first version. {% endhint %} ## How to verify * Connected integrations are limited to the intended workflow * Trigger Access and Tool Access match the business need * The owning team can inspect Event Feed and Audit * Admin-only workspace actions are limited to the people who should manage workspace settings and credentials ## Common failures * Overscoped integrations * Shared ownership with no clear reviewer * Treating a successful connection as a completed security review * Using a personal connection for a workflow that should belong to a team ## Next step * [Quickstart for automation engineers](/overview/quickstart-engineer) * [Safe rollout](/event-feed/safe-rollout) * [Solutions Engineering Access](/workspace-settings/solutions-engineering-access) * [Environments and Sandbox](/workspace-settings/environments-and-sandbox) # Solutions Engineering Access ## What this is Solutions Engineering (SE) access allows Protege AI staff to view or edit your Hookshot™ workspace configuration for support, debugging, and setup assistance. It is a controlled overlay that does not create a normal workspace membership. ## When to use it Use this page when you need to: * Grant Protege AI support staff access to your workspace * Review or revoke an existing SE access grant * Understand what SE users can and cannot do ## What you need first * Workspace owner or admin role * A request from Protege AI support () identifying the access level needed ## Steps ### 1. Open SE Access settings Go to **Settings** and find the **Solutions Engineer Access** section. This section is visible only to workspace owners and admins. ### 2. Choose the access level | Level | What it allows | | --------- | ----------------------------------------------------------------------------------- | | **Read** | View workspace configuration, teams, people, Protege setup, and integrations | | **Write** | Edit workspace configuration, manage teams, configure Proteges, and modify settings | Read access is appropriate for diagnostic sessions. Write access is appropriate when Protege AI staff need to adjust configuration on your behalf. ### 3. Choose the duration | Duration | Behavior | | ------------ | ------------------------------------- | | **7 days** | Access expires after 7 days | | **30 days** | Access expires after 30 days | | **90 days** | Access expires after 90 days | | **Standing** | Remains active until manually revoked | Use the shortest duration that covers the support need. Standing access should be reserved for ongoing partnerships. ### 4. Enable access Select the level and duration, then choose **Enable**. The grant becomes active immediately. ### 5. Review active grants The SE Access section shows: * The current access level * The grant mode (temporary or standing) * When the grant was activated * When it will expire (if temporary) ### 6. Revoke access If you want to end access before the expiry date, choose **Revoke**. The grant status changes immediately and the SE user loses access on their next session. ## What SE users can see * **Read access**: Workspace settings, teams and people, Protege configurations, integration connections, Event Feed, and Audit * **Write access**: Everything from read access, plus the ability to edit workspace settings, manage teams and people, create and edit Proteges, and configure integrations ## What SE users cannot do * Manage billing, plans, or payment methods * Grant or modify their own SE access * Access workspaces where no SE grant exists * Bypass the access level they were granted (read-only users cannot edit) ## SE overlay behavior When an SE user has active access, they: * Can see all teams in the workspace, not just one team * Do not appear as a workspace member in the People list * Do not receive workspace notifications or emails * Are not counted against your seat limit {% hint style="info" %} SE access is a support overlay, not a membership. SE users are Protege AI staff who enter your workspace for a defined period and purpose. They do not become workspace members. {% endhint %} ## Sandbox and environment access SE access is granted **per workspace**. If your workspace is linked to a sandbox environment, granting SE access to the production workspace does **not** automatically grant access to the sandbox — and vice versa. To give an SE user access to both environments: 1. Grant SE access in the **production** workspace's Settings page 2. Switch to the **sandbox** workspace (using the workspace picker in the sidebar) 3. Grant SE access in the **sandbox** workspace's Settings page Each environment's SE access is independently controlled. You can choose different access levels or durations for each. For example, you might grant standing write access to the sandbox for ongoing configuration work, but only temporary read access to production for a specific diagnostic session. When an SE user has active access to both environments, the sidebar workspace picker shows both the production and sandbox workspaces. The sandbox entry is labeled with **Sandbox** so you can tell the environments apart at a glance. {% hint style="info" %} SE access in a sandbox workspace is subject to the same sandbox restrictions as regular membership — team and people administration is inherited from the production workspace and cannot be changed independently. {% endhint %} See [Environments and Sandbox](/workspace-settings/environments-and-sandbox) for more on how production and sandbox workspaces are linked. ## When access expires Temporary grants automatically expire at the end of their duration. When a grant expires: * The SE user can no longer access the workspace * No data is removed or changed * The grant record remains visible in the SE Access section for audit purposes ## How to verify * The SE Access section shows the correct level and duration * The expiry date matches the duration you selected * Revoking access immediately removes the SE user's ability to enter the workspace ## Common failures * Granting write access when read access would suffice * Choosing standing access when a temporary grant covers the need * Forgetting to revoke access after a support engagement ends * Confusing SE access with workspace membership * Assuming SE access to the production workspace also grants access to the sandbox ## Next step * [Environments and Sandbox](/workspace-settings/environments-and-sandbox) * [Workspace Settings](/workspace-settings) * [Security and Permissions](/workspace-settings/security-and-permissions) # Environments and Sandbox ## What this is Hookshot™ supports linking two workspaces together as a production and sandbox pair. The sandbox is a dedicated workspace where you can build and test Protege configurations before promoting them to production. ## When to use it Use environments when you want to: * Test Protege configurations in an isolated workspace before deploying to production * Make changes to behavior prompts, tool access, or schedules without affecting live workflows * Promote tested configurations from sandbox to production with a single action ## What you need first * A production workspace that is already bootstrapped * Contact Protege AI support () to set up a sandbox workspace linked to your production workspace ## How environments work ### Production and sandbox pairing An environment link pairs exactly one production workspace with one sandbox workspace. Each workspace can only belong to one pair. | Property | Production | Sandbox | | ---------------- | ------------------------------------- | ------------------------------------------------------------------- | | Purpose | Live workflows and real data | Testing and staging configurations | | Proteges | Running and serving events | Copies promoted from production, or new configurations being tested | | Credentials | Live connections to external services | Can use separate or shared connections | | People and teams | Managed directly | Inherited from production (read-only) | ### Switching between environments When your workspace is part of an environment pair, the sidebar workspace picker shows both workspaces. The sandbox entry is labeled with **Sandbox** so you can distinguish it from production at a glance. Select the sandbox workspace to work on test configurations. Select the production workspace to manage live workflows. ## Protege promotion ### How promotion works Promotion copies a Protege's configuration from the sandbox to the linked production workspace. The following fields are promoted: * Name and description * Behavior prompt (system prompt) * Model selection * Tool access grants * Engine configuration * Schedule definitions ### What is not promoted The following are kept separate and are **not** overwritten during promotion: * Integration credentials and connections * Webhook secrets and provider resource IDs * Run history and feed history * Trigger event history This means promoting a sandbox Protege to production preserves the production Protege's live connections and run data. ### Drift detection If a production Protege is edited directly outside of promotion, it is marked as **drifted**. The next promotion will warn about the drift and overwrite the changed configuration fields. This helps you understand when manual changes to production may be lost. ## Sandbox workspace restrictions Because the sandbox inherits administration from its linked production workspace, the following restrictions apply: * **People**: You cannot invite new people to the sandbox. Membership is inherited from the production workspace's owners and admins. * **Teams**: You cannot create, rename, or delete teams in the sandbox. The default team and its membership mirror the production workspace. * **SE access**: SE access must be provisioned separately in each environment. Granting SE access in the production workspace does not grant it in the sandbox, and vice versa. See [Teams and People](/workspace-settings/teams-and-people) for more on sandbox restrictions for team and people management, and [Solutions Engineering Access](/workspace-settings/solutions-engineering-access) for SE access across environments. ## How to verify * The workspace picker shows both production and sandbox, with the sandbox clearly labeled * Promoting a sandbox Protege updates the production Protege's configuration without affecting its credentials or history * Changes made directly to a production Protege are flagged as drift on the next promotion ## Common failures * Editing a production Protege directly instead of making changes in the sandbox and promoting * Assuming SE access in one environment grants access to the other * Expecting promotion to copy credentials or connection state from sandbox to production * Forgetting that sandbox team and people changes are not allowed — they must be made in the production workspace ## Next step * [Solutions Engineering Access](/workspace-settings/solutions-engineering-access) * [Teams and People](/workspace-settings/teams-and-people) * [Workspace Settings](/workspace-settings) # Getting Support #### Getting Support At Protege AI, we understand the importance of timely assistance to ensure the smooth operation of your legal content review processes. We offer multiple channels for you to reach out to our support team: 1. **Email Support**: For formal inquiries, detailed explanations, or any assistance you may need, you can reach us via email at . Our support team monitors this inbox closely and strives to respond promptly to all queries. 2. **Shared Slack Support (Enterprise)**: For enterprise clients, we can set up a shared Slack channel during onboarding for rapid collaboration with your team. When reaching out for support, please provide as much detail as possible regarding the issue you're facing. This could include screenshots, error messages, or steps to reproduce the problem. The more information you provide, the more accurately we can assist you. Our support team operates during Pacific time business hours, and we strive to address all inquiries in a timely manner. If you encounter an urgent issue outside of our regular support hours, please send an email marked urgent in the subject to . We'll do our best to prioritize your request. We're committed to ensuring your experience with Protege AI is seamless and productive. Don't hesitate to reach out whenever you need assistance – we're here to help! # Release Notes If you encounter any issues or have questions about new features, please don't hesitate to contact our support team at . We're here to assist you throughout the process. To request access to our latest agent platform, Hookshot, which can be integrated with Protege Review, contact us or reach out over Slack. **May 2026** * **Upgraded Vision Model Defaults**: Vision-based policy steps and OCR workflows improving image understanding and visual policy-review performance. **April 2026** * **Simplified Model Lineup**: Removed Maverick from the available model lineup to streamline model selection and keep policy-review defaults aligned with the latest supported models. **March 2026** * **One-Time Scan Page for Content Scanner**: Added support for running one-time scans more directly from the Content Scanner workflow, making ad hoc reviews faster. * **Improved Vision Prompt Image Handling**: Enhanced the way image inputs are processed for vision-based policy steps, improving reliability for image and screenshot review. * **Upgraded Model Defaults**: Refreshed model naming and configuration to better reflect the current supported model lineup across policy and vision workflows. **February 2026** * **Workspaces**: Introduced workspace-based organization across Protege, making it easier to separate policies, documents, scanner activity, and related review workflows by team or business area. * **Workspace-Aware Notifications**: Notifications and digests now better reflect workspace context, helping users understand which workspace an alert or update belongs to. **November 2025** * **Long Form Document Review**: Introduced support for reviewing long-form documents with improved handling of multi-page content, better context retention, and optimized processing for large documents. * **Duplicate Feedback Prevention**: Implemented automatic detection and prevention of duplicate task creation for identical feedback items, reducing noise and improving workflow efficiency. * **Expandable Table Rows**: Added expand/collapse functionality for long question text in tables, improving readability and user experience when reviewing detailed policy questions. * **Shadow Model Testing**: Released shadow mode capability for testing new AI models alongside production models without affecting user experience. * **Policy Engine Ordering**: Improved policy execution ordering and management in the Policy Engine for more predictable and efficient policy application. **October 2025** * **New Content Tab in Scanner**: Introduced a dedicated "New Content" tab in the Content Scanner dashboard to easily view and filter newly discovered or changed content across all monitored sources. * **Task Manager Analytics**: Added comprehensive analytics for task managers including regulatory actions tracking, project insights, and detailed metrics on review workflows. * **Regulatory Email Integration**: Launched automated email monitoring for regulatory communications, enabling automatic ingestion and review of compliance-related emails. * **Assistant Use Cases**: Expanded AI Assistant capabilities with new specialized use cases for regulatory research, policy analysis, and compliance workflows. **September 2025** * **AI Assistant Tool**: Introduced a new AI Assistant with comprehensive access to all Protege data, enabling intelligent queries and insights across your entire environment for enhanced workflow automation and data discovery. * **Shareable Document Review Links**: Share document reviews with external users outside your organization using password-protected links. External user login data and access analytics are available upon request for compliance and audit tracking. **August 2025** * Real-time Asana Integration: Asana task changes are now pushed directly to Protege in real-time, eliminating sync delays and helping ensure your project management updates are immediately reflected across both platforms. **July 2025** * Teach your AI Approvals: All Teach your AI submissions now require approval in the Policy Engine before being used for model training to prevent misleading instructions from entering the finetuning process. You can edit or delete submissions during review, and optionally enable 3-day auto-approval for streamlined workflows. * Notification Inbox: Access all your notifications in one centralized location with the new Notifications tab. View a complete history of Content Scanning policy alerts, Teach your AI updates, and reminders items. * Daily Email Digest: Stay informed without constant interruptions. Enable daily business day email summaries to receive a consolidated overview of all notifications, policy feedback, and system updates delivered once per day during business hours. **June 2025** * Acknowledge Feedback: Users can now acknowledge feedback items to confirm they have been seen, without marking them as resolved—improving transparency and tracking of feedback that requires further review or action. * Change Vision Models: Switching Vision Models is available upon request, message or your support team to change it for any Policy step. * Thumbs Up Feedback: Teach your AI that it's flagging the correct items. * Display of Non-Visible Text: Webpages that are monitored by the Content Scanner now show a "Hidden Text" field. This field captures non-visible text — meaning text not shown to users directly (e.g., hidden via CSS, off-screen positioning, or within meta tags). * Auto Risk Levels: Policy feedback can now be automatically classified as High, Medium, or Low based on LLM prompt-based definition and a configurable default level. **May 2025** * Default Brand Attributes: Use a Linked Database Sheet as a record for the default Attributes for all the Brands in your environment * Content Scanner Dashboard Upgrade: The dashboard now includes richer metrics, including the ability to view and filter scan jobs by brand. * Attachment Scanning Optimizations: Improved algorithms for calculating file similarity to reduce unnecessary repeat scans, helping lower client token usage. * User Feedback Session Recordings: For error investigation and feature improvement, Protege may temporarily access video-based session click data leading up to a suboptimal or failed interaction. Recordings are automatically deleted within 7 days. To opt out, contact . * Similar Usage: Users can now view all instances of similar phrasing across scanned pages and reviewed documents for any policy type (e.g., product comparisons, free stuff, legal qualifiers).—*not just for claims.* This helps teams identify recurring marketing language and help ensure all prior approved language is easily accessible. * Real-time Sync Feedback for Tasks: When manually syncing tasks with Jira, Asana, or other integrations, you’ll now see real-time status updates directly in the dashboard. **April 2025** * Introduction of Llama 4 Maverick and Scout for analysis. * Upgraded all large vision models to use Llama 4 for analysis. * Mark as Reviewed in Content Scanner: Individual pages and full reports can now be marked as reviewed to track which pieces of content have been reviewed. * Content Difference Analysis in Content Scanner: Website pages that have not changed since the last scan will now skip AI processing to save tokens. A link to the original scan of that page version will be shown. * Performance increase: AI scans of documents have been optimized for load time. * Change document attributes from within the Google Doc Extension. **March 2025** * Redesigned “Teach Your AI” Experience: Instruct your AI model to either skip or focus on specific types of feedback during document reviews. * Nightly Agent Updates: Enterprise clients with customized ShieldLlama models now enjoy nightly model retraining for improved performance. * New Analytics on the Agents Page: Monitor model accuracy and rollback models easily. * Chrome Extension Helper Released: Speeds up Google Docs reviews with a dedicated helper extension. * AI Explanations for Policies: Gain clear, detailed explanations for every policy decision. * Resolved Feedback Section: A new section now shows AI feedback that has been *resolved*, *ignored*, or *actioned*. **February 2025** * Nightly Trainable ShieldLlama Base Model: Experience enhanced performance with daily retraining of your base model. * Protege Sandbox Environment Launched: Enterprise clients can now test and experiment in a dedicated sandbox environment. * Prohibited Content Policy Released: New guidelines have been introduced to enforce stricter content standards. * General Policy Document Review: A streamlined review process for policy documents has been implemented. **January 2025** * Search across all Documents in your Protege environment * Release of Archiving for long-term document retention with storage support for multiple clouds. * Airtable Connectors for Attribute management. * YouTube scanning for web monitor and social media influencer **December 2024** * Enhanced audio transcription: Upgrades to the audio transcript service for faster speed and improved accuracy. * Improvements to Similar Claims accuracy: We upgraded the AI model used for generating Similar Claims. All existing claims will be migrated over without user action. **November 2024** * Support for Wrike Workspace and Asana Teams: Users can now add all projects from Wrike Workspace and Asana teams to Protege for streamlined project management. * Skip Attachment Processing Mode: Introduced a new mode to bypass attachment processing for projects and workspaces, enhancing flexibility in data handling. * Updated FinTech AI Policies: Enhanced FinTech AI policies to align with industry standards and address evolving compliance requirements. * Document Page: Store files in the Document tab for AI testing, data labeling, and saving for long-term archiving. * Custom Roles for Access Control: Added the ability to create custom roles for more granular access control permissions, empowering administrators with tailored user management. * Typo Detection AI Policy: Released an AI-driven policy for typo detection in marketing brand and voice reviews to improve content accuracy and alignment with brand standards. * Photoshop Asset Policy Review: Seamlessly review Photoshop assets for compliance with policies set in Protege AI, enabling efficient design and compliance workflows. * False Positive Prevention - Negative Label Comparison: Improved handling of false positives by allowing better comparison of negative labels, reducing manual effort. * False Positive Prevention - Cross-Medium Deduplication: Feedback across different mediums (e.g., audio and visual text) is now deduplicated, helping reduce the need to review similar text in multiple places. * False Positive Prevention - Document-Level Exceptions: Set exceptions for specific documents, allowing the AI to ignore certain phrases or policies in context. * False Positive Prevention - Brand-Level Exceptions: Apply exceptions across an entire brand for consistent handling of repetitive compliance issues. * False Positive Prevention - Environment-Wide Exceptions: Extend exceptions to the entire Protege environment, enhancing flexibility in policy application. * Subset Deduplication: When AI detects both a phrase and its containing sentence as independently triggering, Protege will now display the most appropriate feedback. * Prompt Tuning (Assisted): Refine AI prompts with AI to improve accuracy and alignment with specific policy goals based on past labeled Exceptions, reducing false positives and negatives. **October 2024** * Non-Compliance Remediation Page: Added a new page to remediate non-compliance issues. Users can connect a project to Asana or Jira to track issues, assign tasks, and collaborate with cross-functional teams more efficiently. * Query-Based Large Vision Models: Added query-based large vision models to identify specific compliance issues. Users can put a Prompt Identification step such as, “Identify any objects that look like a credit card, debit card, or prepaid card on this page.” to detect if there are payment cards on that page. * Claims Approval Page: Added the ability to connect Asana or Jira task managers to the Claims Approval page for claim submission and approval processes, and streamlining the submission and storage within the Decision Store. * Influencer Monitoring Tracking Page: Introduced a new page to monitor influencer content across social media platforms for compliance with legal and brand guidelines. Automatically track posts, detect non-compliant content, and link to Asana or Jira for seamless issue tracking and resolution. Enhance campaign oversight with real-time alerts and detailed reporting on influencer activities. With this page, you can help ensure your content complies with advertising guidelines, such as disclosure requirements, FTC regulations, and platform-specific policies. **September 2024** * Facebook Page Scanner: Introduced a new scanner to automatically monitor and analyze content on Facebook pages for policy violations and compliance monitoring. * Apple App Store Listing Page Scanner: Added a new scanner to automatically review app descriptions, images, and metadata for policy compliance on Apple App Store listings, providing detailed reports on potential issues. * Android Play Store Listing Page Scanner: Launched a new scanner to automatically review app descriptions, images, and metadata for policy compliance on Android Play Store listings, providing detailed reports on potential issues. * Scanner Reports and Jobs Enhancements: Added new sorting and filtering options on the Scanner Reports and Scanner Jobs pages, allowing for more efficient navigation and management of scan data. * Shareable Filtered Links: Introduced the ability to share applied filters on the content scanner with teammates via shareable links, making collaboration and data review more streamlined. * Scan Report Naming: Introduced the ability to organize scan results more efficiently by assigning custom names to one-time and recurring jobs, streamlining result management and retrieval. * Multi-Variable Attributes: Added support for assigning multiple attribute values to each piece of reviewed marketing, allowing for more detailed and flexible classification and analysis. **August 2024** * Microsoft Word 365 Add-In: Enhanced speed, with noticeable reductions in the time required to display the first result and show all results. * Google Extensions: Enhanced speed, with noticeable reductions in the time required to display the first result and show all results. * Open-Source Large Language Models: Access new open-source large language models to execute your Steps faster. * Attributes Feature Support: Now supports the creation of new attributes for Tasks. You can set Attributes in Settings and designate text languages (e.g., disclosures) from a Google Sheet. Protege AI will automatically adjust the execution of Policies and Steps for each Task based on the assigned Attributes. * Multi-Language Document Translation and Review: We now support AI translation of documents in languages other than English, allowing for quick human and AI Policy review. * Copy Policy: Duplicate a Policy and add it to any Policy Group in your environment. **July 2024** * On the Task Page, a “Change Document Evaluation Type” selector has been added. Changing this option will automatically rescan all attachments for the Task. * The Task page now shows Activity and Comments from linked Jira or Asana tasks. * We’ve improved zoom in/out features and added a 100% size button for viewing Image and PDF files. * You can now filter Decision Store records by Brand. * You can export Trademark and Claim records from a Decision Store to a CSV file. * Brand Selection is now available during Document Reviews. You can choose a brand when reviewing documents from Google Workspace, Microsoft Office, and the Figma extension. * The Figma extension now supports scanning a single selected Figma frame instead of the entire page. * Wayback Mode lets you see all Scans over time for a specific web URL being monitored in Content Scanner. You can quickly navigate to other scanned pages on that domain. * Protege AI now automatically adds comments with QA review links in new Jira and Asana Tasks. * Policy Feedback titles can now be customized along with new highlighting colors, and changes can be made from the Label field in the Policy Engine. **June 2024** * Content Scanner now supports LinkedIn and X. * Risk Scores (High, Medium, and Low) are available for Trademarks, Claims, and Policy Feedback Cards. * Actions - a series of automated steps that can be triggered after a document is analyzed by Protege AI. The initial launch includes: * Sending all AI Feedbacks above a customer-assignable risk threshold to Asana and Jira. * Approving a marketing review request if the documents are below a certain risk threshold. * Creating a new Asana or Jira ticket with a list of issues to fix if Content Scanner results are above a certain risk threshold. **May 2024** * Automated document review integration with Microsoft Office 365 SharePoint when files are linked in Asana and Jira tickets. * Automated document review integration with Frame.io when review links are attached in Asana and Jira tickets. * Enhanced sorting and filtering options on the Task list page. * Zooming and panning capabilities for PDF and image attachment previews. * Ability to comment from Protege AI to Asana, Jira, and Frame.io. * Detailed explanations for Policy Engine actions. * New Protege AI plug-in for Figma. * Self-service creation for one-time and recurring Web Scan jobs. **April 2024** * Secure OAuth login for Jira Task Manager Review. * New integrations with Asana, Wrike, and Smartsheets for automated ticket review. * Automated document review for linked Google Docs and Slides in Jira and Asana tickets. * Microsoft Word 365 Add-In for Protege AI. * UX enhancements to the Protege AI Dashboard. * Introduction of approval audit reports. **March 2024** * Support for up to 100-page Google Slides and very long Google Docs. * New UX for AI feedback in the Google Workspace sidebar. * Dashboard bug fixes. * Improved admin account permissions, user roles, and user deletion options # Document Editor Installation This setup guide will walk you through the process of integrating Protege Al into your team's editor tools. Support is currently available for both Microsoft Word and Google Workspace (Docs and Slides).\ \ Whether you're in compliance, legal, or marketing, Protege AI aims to assist you in ensuring compliance and accuracy in your marketing materials. Our tool is designed to provide feedback on claims, trademarks, and company marketing guideline policies.
{% content-ref url="/pages/StFAm6N63RVROIM34sfI" %} [Google Workspace](/review/getting-started/document-editor-installation/google-workspace) {% endcontent-ref %} {% content-ref url="/pages/HYsRkMjSPaC9g0SgVSri" %} [Office 365](/review/getting-started/document-editor-installation/office-365) {% endcontent-ref %} {% content-ref url="/pages/bNAeqJAibMxQQauptY6G" %} [Figma](/review/getting-started/document-editor-installation/figma) {% endcontent-ref %} {% content-ref url="/pages/FTDEFx8pXIiAKRGjNA6b" %} [Adobe Creative Cloud](/review/getting-started/document-editor-installation/adobe-creative-cloud) {% endcontent-ref %} # Google Workspace Protege AI’s Google Workspace plugin integrates directly with Google Docs and Slides, allowing marketing and legal teams to review content for legal and compliance risks without leaving their documents.
In addition to the plugin, we offer a Chrome Extension that unlocks advanced features like in-line commenting for deeper collaboration. To use the plugin, you’ll need a Google Workspace account. #### 🔧 Browser Compatibility Protege is tested and fully compatible with Google Chrome and Brave browsers. ## **Part 1.** Installing the Google Workspace Plugin You can install the plugin in two ways: * IT Admin Installation – for organization-wide deployment. * Individual User Installation – for single machine install. #### {% tabs %} {% tab title="Individual Installation" %} 1. **Access Google Workspace Marketplace**: Log in to your Google Workspace account. 2. **Navigate to Marketplace**: Visit the listing for [Protege for Google Workspace Marketplace](https://workspace.google.com/marketplace/app/protege_ai/72543460431) 3. **Install the Plugin**: On the Protege Plugin listing, select "Individual Install." Follow the on-screen instructions to complete the installation.
4. **Grant Permissions**: Grant the necessary permissions to the plugin when prompted. 5. **Complete Installation**: Once installed, the plugin will be accessible within your Google Workspace (Docs and Slides). 6. **Test the Plug-In:** Open a new Google Document and enter the text you want reviewed. Navigate to the Extensions tab, select "Protege AI", and then select "Open".
{% endtab %} {% tab title="IT Admin Installation" %} 1. **Admin Console Access**: As an IT Admin, log in to your Google Workspace Admin Console. 2. **Navigate to Marketplace**: Visit the listing for [Protege for Google Workspace Marketplace](https://workspace.google.com/marketplace/app/protege_ai/521295007931) 3. **Install the Plugin**: On the Protege Plugin listing, select "Admin Install." Follow the on-screen instructions to complete the installation.
4. **Review Permissions**: Review the permissions required by the plugin and confirm the installation. 5. **Deployment Settings**: Configure deployment settings as per your organization's requirements. You may choose to deploy the plugin to all users or specific organizational units. 6. **Complete Installation**: Once configured, complete the installation process. The plugin will now be available to all users within your organization. {% endtab %} {% endtabs %} ## Part 2. Chrome Extension Installation 1. **Navigate to Marketplace**: Visit the listing for [Protege for Google Chrome](https://chromewebstore.google.com/detail/protege-ai/pknoakkhmfneejkpnjfgkcnphpjhjcmf) 2. **Install the Chrome Extension**: On the Protege Plugin listing, select "Add to Chrome" Follow the on-screen instructions to complete the installation.
#### #### Note: * If you encounter any issues during the installation process or require assistance, please reach out to our support team at . We're here to help ensure a smooth installation and seamless integration with your workflow. # Office 365 The Protege AI Add-In for Office 365 seamlessly integrates with your existing workflow, empowering marketing and legal teams to streamline content review for legal risks directly within your Word editor. From Sharepoint or Microsoft 365 Word, you can install the plug-in with these instructions. 1. Select **File** > **Get Add-ins**, then select **Manage my Add-Ins**
2. Click **More Add-ins**, and enter "**Protege"** in the search bar.
3. Press **Add**, and follow the on-screen instructions to install the add-in. 4. Verify that the Protege AI add-in is installed. Select the **Protege AI** tab at the navigation ribbon, and then press **Open Protege AI.**
#### Note: * If you encounter any issues during the installation process or require assistance, please reach out to our support team at . We're here to help ensure a smooth installation and seamless integration with your workflow. # Figma The Protege AI plugin for Figma seamlessly integrates with your design workflow, empowering you to verify the content matches compliance standards. Follow these instructions to install the plugin. 1. Open your web browser and go to [Protege AI on Figma Community](https://www.figma.com/community/plugin/1375519663421399107/protege-ai). Select **Open in Figma** on the left side of the screen.
2. Open Figma and navigate to your design file. Select the Figma icon in the top left corner to open the main menu. Choose **Plugins** from the dropdown menu, and select **Protege AI**.
3. Follow the on-screen instructions to start Protege AI. #### Note: * If you encounter any issues during the installation process or require assistance, please reach out to our support team at . We're here to help ensure a smooth installation and seamless integration with your workflow. # Adobe Creative Cloud The Protege AI plugin for Adobe Creative Cloud seamlessly integrates with your Photoshop design workflow, empowering you to verify the content matches compliance standards. Follow these instructions to install the plugin. 1. Open Adobe Creative Cloud and go to Stock & Marketplace. Enter **Protege AI** on the search bar of the screen.
2. Follow install instructions to load Photoshop. 3. Log in with your admin provided credentials. #### Note: * If you encounter any issues during the installation process or require assistance, please reach out to our support team at . We're here to help ensure a smooth installation and seamless integration with your workflow. # Task Manager Setup In Protege, you have the flexibility to link your team's preferred task management tools. Integrations provide seamless access to your documents for automated review during intake for your AI policies. Below, we provide instructions for setting up the integrations with Protege AI. **Task Managers** {% content-ref url="/pages/t9XrKPabSPzIAqyxMkiR" %} [Asana](/review/getting-started/task-manager-setup/asana) {% endcontent-ref %} {% content-ref url="/pages/BcgJePbulg9WRjwa3ZcH" %} [Jira](/review/getting-started/task-manager-setup/jira) {% endcontent-ref %} {% content-ref url="/pages/6odAP1nXnMHmr1ti9GYZ" %} [Smartsheets](/review/getting-started/task-manager-setup/smartsheets) {% endcontent-ref %} {% content-ref url="/pages/aAa8kiAHRlWhHFnKNZES" %} [Wrike](/review/getting-started/task-manager-setup/wrike) {% endcontent-ref %} #### Note: * Currently, Protege supports the listed integrations. If you do not see your preferred tool, contact to request additional tools. # Asana If your team organizes review requests through Asana, you can link the Asana Project to appear in Protege AI's dashboard for task management. 1. **Access the Dashboard**: Log in to your Protege account via the dashboard at [app.tryprotege.com](https://app.tryprotege.com). 2. **Navigate to Settings**: Once logged in, navigate to the "Settings" section of the dashboard. This is located at the bottom of the navigation sidebar. 3. **Link Asana**: Within the Settings section, select the option "Task Managers." On that page, click on set up new integration option to begin the process. * It is recommended to create an Asana user under protege-bot@\[your company name].com. Comments and feedback left through Protege AI will show up under this identity.
4. **Authorize Access**: You will be redirected to the Asana sign-in page. Enter your Asana account credentials to authorize Protege AI to access your Asana projects.
5. **Select Project Board**: Once authorized, you will be prompted to select the specific project board within Asana that you want to link to Protege AI. You can also select the Default Evaluation Type for the board. Leave blank for AI autorecommend to be used.
6. **Confirmation**: After selecting the project board, you will receive confirmation that Asana has been successfully linked to your Protege AI account. 7. **Start Reviewing**: With Asana linked, you can now preview your tasks and files to review in Protege AI for efficient task management. Note: * If the user who linked the board leaves the company or no longer has access, the board will need to be relinked. * If you encounter any issues during the installation process or require assistance, please reach out to our support team at . We're here to help ensure a smooth installation and seamless integration with your workflow. \
# Jira If your team organizes review requests through Jira, you can link the Jira Project to appear in Protege AI's dashboard for task management. 1. **Access the Dashboard**: Log in to your Protege account via the dashboard at [app.tryprotege.com](https://app.tryprotege.com). 2. **Navigate to Settings**: Once logged in, navigate to the "Settings" section of the dashboard. This is located at the bottom of the navigation sidebar. 3. **Link Jira**: Within the Settings section, select the option "Task Managers." On that page, click on set up new integration option to begin the process. * It is recommended to create a Jira user under legal@\[your company name].com. Comments and feedback left through Protege AI will show up under this identity.
4. **Authorize Access**: You will be redirected to the Jira sign-in page. Enter your Jira account credentials to authorize Protege AI to access your Jira projects and boards.
5. **Grant Permissions**: After signing in, Jira will request permission for Protege AI to access your projects and boards. Review the permissions requested and grant access as necessary. 6. **Select Project Board**: Once authorized, you will be prompted to select the specific project board within Jira that you want to link to Protege AI.
7. **Confirmation**: After selecting the project board, you will receive confirmation that Jira has been successfully linked to your Protege AI account. 8. **Start Reviewing**: With Jira linked, you can now preview your tasks and files to review in Protege AI for efficient task management. Note: * If the user who linked the board leaves the company or no longer has access, the board will need to be relinked. * If you encounter any issues during the installation process or require assistance, please reach out to our support team at . We're here to help ensure a smooth installation and seamless integration with your workflow. \
# Smartsheets If your team organizes review requests through Smartsheets, you can link Reports or Sheets to appear in Protege AI's dashboard for task management. 1. **Access the Dashboard**: Log in to your Protege account via the dashboard at [app.tryprotege.com](https://app.tryprotege.com). 2. **Navigate to Settings**: Once logged in, navigate to the "Settings" section of the dashboard. This is located at the bottom of the navigation sidebar. 3. **Link Smartsheets**: Within the Settings section, select the option "Task Managers." On that page, click on set up new integration option to begin the process.
4. **Authorize Access**: You will be redirected to the Smartsheets sign-in page. Enter your Smartsheets account credentials and authorize Protege AI to access your Sheets and Reports.
5. **Select a Report or Sheet**: Once authorized, you will be prompted to select the specific Smartsheet file that you want to link to Protege AI. Selecting "Sheets" shows all Smartsheet Sheets you have access to and switching to "Reports" shows all Smartsheet Reports you have access to.
6. **Verify Field Mapping:** When a Sheet or Report is selected, Protege AI will read through all the columns in the file to map over. You can change the fields used by selecting the dropdowns under the Smartsheets column.
7. **Confirmation**: After selecting the project board, you will receive confirmation that Smartsheets has been successfully linked to your Protege AI account. 8. **Start Reviewing**: With Smaartsheets linked, you can now preview your tasks and files to review in Protege AI for efficient task management. Note: * If the user who linked the Sheet or Report leaves the company or no longer has access, the task manager will need to be relinked. * If you encounter any issues during the installation process or require assistance, please reach out to our support team at . We're here to help ensure a smooth installation and seamless integration with your workflow. \
# Wrike If your team organizes review requests through Wrike, you can link the Wrike Project to appear in Protege AI's dashboard for task management. 1. **Access the Dashboard**: Log in to your Protege account via the dashboard at [app.tryprotege.com](https://app.tryprotege.com) 2. **Navigate to Settings**: Once logged in, navigate to the "Settings" section of the dashboard. This is located at the bottom of the navigation sidebar. 3. **Link Wrike**: Within the Settings section, select the option "Task Managers." On that page, click on set up new integration option to begin the process.
4. **Authorize Access**: You will be redirected to the Wrike sign-in page. Enter your Wrike account credentials to authorize Protege AI to access your Wrike projects and boards. 5. **Grant Permissions**: After signing in, Wrike will request permission for Protege AI to access your projects and boards. Review the permissions requested and grant access as necessary. 6. **Select Project Board**: Once authorized, you will be prompted to select the specific project board within Wrike that you want to link to Protege AI.
7. **Confirmation**: After selecting the project board, you will receive confirmation that Wrike has been successfully linked to your Protege AI account. 8. **Start Reviewing**: With Wrike linked, you can now preview your tasks and files to review in Protege AI for efficient task management. Note: * If the user who linked the board leaves the company or no longer has access, the board will need to be relinked. * If you encounter any issues during the installation process or require assistance, please reach out to our support team at . We're here to help ensure a smooth installation and seamless integration with your workflow. \
# File Scanning Setup If your files are created and shared in 3rd party tools like Microsoft Office Sharepoint, Google Docs, or Frame.io, you can setup Protege AI to scan attached links to Task Manager tickets. {% content-ref url="/pages/StFAm6N63RVROIM34sfI" %} [Google Workspace](/review/getting-started/document-editor-installation/google-workspace) {% endcontent-ref %} {% content-ref url="/pages/jnrByyxwy9zY5sJRca34" %} [Office 365 Sharepoint](/review/getting-started/file-scanning-setup/office-365-sharepoint) {% endcontent-ref %} {% content-ref url="/pages/BLCdAlvQ2E8Y9VdakpUv" %} [Frame.io](/review/getting-started/file-scanning-setup/frame.io) {% endcontent-ref %} # Google Workspace If your team uses Google Docs or Google Slides, you can provide Protege AI access for automated review when a ticket is submitted with reference to Google Workspace Document. Complete the setup with these steps: 1. **Access Settings**: Log in to your Protege Counsel account and navigate to the "Settings" section. 2. **Link Google Workspace**: Within the Settings section, locate the option to "File Access". Click on the Google Workspace option to begin the process.
3. **Authorize Access**: You will be redirected to the Google sign-in page. Enter your Google Work account credentials.
4. **Grant Permissions**: After signing in, Google will request permission for Protege Counsel to access your Google Workspace files. Review the permissions requested and grant access as necessary. The permissions authorize Protege Counsel to access your Google Docs and Slides files. 5. **Confirmation**: Once authorized, you will receive confirmation that your Google Workspace has been successfully linked to your Protege Counsel account. 6. **Access Linked Files**: After linking Google Workspace, you can access your files directly within Protege Counsel for efficient content review and analysis. Notes: * For security purposes, ensure you only link file storage tools that you regularly use for marketing review. * If you encounter any issues during the linking process or have questions about accessing your files, please contact our support team at for assistance. We're here to help ensure a smooth integration with your preferred file storage tools. # Office 365 Sharepoint If your team uses Microsoft Office 365, you can provide Protege AI access for automated review when a ticket is submitted with reference to a Sharepoint Document. Complete the setup with these steps: 1. **Access Settings**: Log in to your Protege AI account and navigate to the "Settings" section. 2. **Link Sharepoint**: Within the Settings section, locate the option to "File Access". Click on the Sharepoint option to begin the process.
3. **Authorize Access**: You will be redirected to the Microsoft sign-in page. Enter your account credentials.
4. **Grant Permissions**: After signing in, Sharepoint will request permission for Protege AI to access your files. Review the permissions requested and grant access as necessary. The permissions authorize Protege AI to access your Sharepoint documents that are linked in tickets. 5. **Confirmation**: Once authorized, you will receive confirmation that your Sharepoint has been successfully linked to your Protege AI account. 6. **Access Linked Files**: After linking Sharepoint, you can access your files directly within Protege AI for efficient content review and analysis. Notes: * For security purposes, ensure you only link file storage tools that you regularly use for marketing review. * If you encounter any issues during the linking process or have questions about accessing your files, please contact our support team at for assistance. We're here to help ensure a smooth integration with your preferred file storage tools. # Frame.io If your team uses Frame.io for sharing marketing content, you can provide Protege AI access for automated review when a ticket is submitted with a frame.io share review link. Complete the setup with these steps: 1. **Access Settings**: Log in to your Protege AI account and navigate to the "Settings" section. 2. **Link Frame.io**: Within the Settings section, locate the option to "File Access". Click on the Frame.io option to begin the process. * Note: It is recommended to create a Frame.io account under legal@\[your company name].com. Comments and feedback left through Protege AI will show up under this identity.
3. **Authorize Access**: You will be redirected to the Frame.io sign-in page. Enter your Frame.io account credentials. 4. **Grant Permissions**: After signing in, Frame.io will request permission for Protege AI to access your Projects. Review the permissions requested and grant access as necessary. The permissions authorize Protege AI to access your videos and share Links.
3. **Confirmation**: Once authorized, you will receive confirmation that Frame.io has been successfully linked to your Protege AI account. 4. **Access Linked Files**: After linking Frame.io, you can access your files directly within Protege AI for efficient content review and analysis. Notes: * For security purposes, ensure you only link file storage tools that you regularly use for marketing review. * If you encounter any issues during the linking process or have questions about accessing your files, please contact our support team at for assistance. We're here to help ensure a smooth integration with your preferred file storage tools. # API Reference Protege exposes an external API for tenant-scoped document review workflows, reference data discovery, scanner job management, and scanner reports. API access is typically enabled as part of an enterprise integration. For packaging guidance, support expectations, and how an optional agent skill fits into a broader rollout, see the enterprise [Integrations & API](/review/enterprise-features/integrations-and-api) guide. This GitBook space includes an API reference generated from the Protege OpenAPI specification. The reference is organized into four groups: 1. `Reference Data` for brands, policies, policy groups, and document evaluation types 2. `Document Reviews` for creating and retrieving reviews 3. `Scanner Jobs` for managing monitoring jobs and run history 4. `Reports` for scanner report summaries and detail views ## Authentication All endpoints use bearer authentication with an external Protege API key. Send requests with: ```http Authorization: Bearer ``` ## Base URL The documented sandbox server for the API is: ``` https://sandbox.tryprotege.com ``` ## Formats The `Create a document review` endpoint supports both: 1. `application/json` for direct text review requests 2. `multipart/form-data` for file upload review requests ## Need Access? If you need an API key, help choosing the right `documentEvaluationTypeId`, or sample requests for your integration, contact the Protege team through your shared support channel or email . # Reference Data Lookup endpoints for the tenant-specific metadata required to drive review and scanner workflows. ## List brands > Retrieve brands available to the authenticated tenant. These brand identifiers can be used when creating scanner jobs or filtering report results. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Reference Data","description":"Lookup endpoints for the tenant-specific metadata required to drive review and scanner workflows."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"BrandListResponse":{"description":"Paginated collection of brands.","type":"object","required":["brands","page"],"properties":{"brands":{"type":"array","items":{"$ref":"#/components/schemas/Brand"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"Brand":{"description":"Brand available to the authenticated tenant for filtering scanners and reports.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/brands":{"get":{"summary":"List brands","description":"Retrieve brands available to the authenticated tenant. These brand identifiers can be used when creating scanner jobs or filtering report results.","operationId":"listBrands","tags":["Reference Data"],"parameters":[{"name":"id","in":"query","description":"Filter by a specific brand identifier.","schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Case-insensitive search against brand names.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of records to return.","schema":{"type":"integer","minimum":1}},{"name":"offset","in":"query","description":"Number of records to skip before returning results.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Brands returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandListResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` ## List policies > Return policy definitions that may be referenced by review findings or nested under policy groups and document evaluation types. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Reference Data","description":"Lookup endpoints for the tenant-specific metadata required to drive review and scanner workflows."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"PolicyListResponse":{"description":"Paginated collection of policies.","type":"object","required":["policies","page"],"properties":{"policies":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"Policy":{"description":"Full policy record returned by the policies endpoint.","allOf":[{"$ref":"#/components/schemas/NestedPolicy"},{"type":"object","properties":{"policyGroup":{"oneOf":[{"$ref":"#/components/schemas/PolicyGroupRef"},{"type":"null"}]}}}]},"NestedPolicy":{"description":"Policy summary embedded under parent resources such as policy groups.","type":"object","required":["id","name","description","useCase","enabled","riskLevel"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"enabled":{"type":"boolean","description":"Whether the policy is currently active and evaluated."},"riskLevel":{"type":"string","description":"Severity or risk classification assigned to this policy."}}},"PolicyGroupRef":{"description":"Lightweight reference to a policy group.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/policies":{"get":{"summary":"List policies","description":"Return policy definitions that may be referenced by review findings or nested under policy groups and document evaluation types.","operationId":"listPolicies","tags":["Reference Data"],"parameters":[{"name":"id","in":"query","description":"Filter by a specific policy identifier.","schema":{"type":"string","format":"uuid"}},{"name":"policyGroupId","in":"query","description":"Filter to policies that belong to a specific policy group.","schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Case-insensitive search against policy names.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of records to return per page.","schema":{"type":"integer","minimum":1,"default":25}},{"name":"offset","in":"query","description":"Number of records to skip before starting the page.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"sortBy","in":"query","description":"Field used to sort the result set.","schema":{"type":"string","enum":["name","createdAt","updatedAt"]}},{"name":"sortOrder","in":"query","description":"Sort direction for the selected sort field.","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Policies returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyListResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` ## List policy groups > Return policy groups available to the tenant. Use the \`expand=policies\` option when clients need the nested policy records in the same response. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Reference Data","description":"Lookup endpoints for the tenant-specific metadata required to drive review and scanner workflows."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"PolicyGroupListResponse":{"description":"Paginated collection of policy groups.","type":"object","required":["policyGroups","page"],"properties":{"policyGroups":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/PolicyGroup"},{"$ref":"#/components/schemas/ExpandedPolicyGroup"}]}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"PolicyGroup":{"description":"Grouping of related review policies used to organize evaluation coverage.","type":"object","required":["id","name","description","useCase"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"prePolicy":{"oneOf":[{"$ref":"#/components/schemas/PolicyPrePolicyRef"},{"type":"null"}]}}},"PolicyPrePolicyRef":{"description":"Reference to a prerequisite or pre-check policy associated with a policy group.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ExpandedPolicyGroup":{"allOf":[{"$ref":"#/components/schemas/PolicyGroup"},{"type":"object","required":["policies"],"properties":{"policies":{"type":"array","items":{"$ref":"#/components/schemas/NestedPolicy"}}}}]},"NestedPolicy":{"description":"Policy summary embedded under parent resources such as policy groups.","type":"object","required":["id","name","description","useCase","enabled","riskLevel"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"enabled":{"type":"boolean","description":"Whether the policy is currently active and evaluated."},"riskLevel":{"type":"string","description":"Severity or risk classification assigned to this policy."}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/policy-groups":{"get":{"summary":"List policy groups","description":"Return policy groups available to the tenant. Use the `expand=policies` option when clients need the nested policy records in the same response.","operationId":"listPolicyGroups","tags":["Reference Data"],"parameters":[{"name":"id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of records to return per page.","schema":{"type":"integer","minimum":1,"default":25}},{"name":"offset","in":"query","description":"Number of records to skip before starting the page.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"sortBy","in":"query","description":"Field used to sort the result set.","schema":{"type":"string","enum":["name","createdAt"]}},{"name":"sortOrder","in":"query","description":"Sort direction for the selected sort field.","schema":{"type":"string","enum":["asc","desc"]}},{"name":"expand","in":"query","description":"Expand related resources inline.","schema":{"type":"string","enum":["policies"]}}],"responses":{"200":{"description":"Policy groups returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyGroupListResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` ## List document evaluation types > Return review configurations available to the tenant. These identifiers are required when creating document reviews or scanner jobs. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Reference Data","description":"Lookup endpoints for the tenant-specific metadata required to drive review and scanner workflows."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"DocumentEvaluationTypeListResponse":{"description":"Paginated list of document evaluation types available to the API key's tenant.","type":"object","required":["documentEvaluationTypes","page"],"properties":{"documentEvaluationTypes":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/DocumentEvaluationType"},{"$ref":"#/components/schemas/ExpandedDocumentEvaluationType"}]}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"DocumentEvaluationType":{"description":"Review configuration that determines which checks, policies, and workflows are applied to a document.","type":"object","required":["id","name","description","useCase"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"}}},"ExpandedDocumentEvaluationType":{"description":"Expanded document evaluation type including its policy groups and nested policies.","allOf":[{"$ref":"#/components/schemas/DocumentEvaluationType"},{"type":"object","required":["policyGroups"],"properties":{"policyGroups":{"type":"array","items":{"$ref":"#/components/schemas/ExpandedPolicyGroup"}}}}]},"ExpandedPolicyGroup":{"allOf":[{"$ref":"#/components/schemas/PolicyGroup"},{"type":"object","required":["policies"],"properties":{"policies":{"type":"array","items":{"$ref":"#/components/schemas/NestedPolicy"}}}}]},"PolicyGroup":{"description":"Grouping of related review policies used to organize evaluation coverage.","type":"object","required":["id","name","description","useCase"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"prePolicy":{"oneOf":[{"$ref":"#/components/schemas/PolicyPrePolicyRef"},{"type":"null"}]}}},"PolicyPrePolicyRef":{"description":"Reference to a prerequisite or pre-check policy associated with a policy group.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"NestedPolicy":{"description":"Policy summary embedded under parent resources such as policy groups.","type":"object","required":["id","name","description","useCase","enabled","riskLevel"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"enabled":{"type":"boolean","description":"Whether the policy is currently active and evaluated."},"riskLevel":{"type":"string","description":"Severity or risk classification assigned to this policy."}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/document-evaluation-types":{"get":{"summary":"List document evaluation types","description":"Return review configurations available to the tenant. These identifiers are required when creating document reviews or scanner jobs.","operationId":"listDocumentEvaluationTypes","tags":["Reference Data"],"parameters":[{"name":"id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"useCase","in":"query","description":"Filter evaluation types by business use case.","schema":{"type":"string","enum":["marketing_review","document_qa"]}},{"name":"limit","in":"query","description":"Maximum number of records to return per page.","schema":{"type":"integer","minimum":1,"default":25}},{"name":"offset","in":"query","description":"Number of records to skip before starting the page.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"sortBy","in":"query","description":"Field used to sort the result set.","schema":{"type":"string","enum":["name","createdAt"]}},{"name":"sortOrder","in":"query","description":"Sort direction for the selected sort field.","schema":{"type":"string","enum":["asc","desc"]}},{"name":"expand","in":"query","description":"Expand related policy groups inline.","schema":{"type":"string","enum":["policyGroups"]}}],"responses":{"200":{"description":"Document evaluation types returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentEvaluationTypeListResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` # Document Reviews Submit documents for review, track processing status, and retrieve completed findings. ## List document reviews > Return document reviews visible to the authenticated tenant. This endpoint is typically used to poll or reconcile asynchronous reviews in bulk. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Document Reviews","description":"Submit documents for review, track processing status, and retrieve completed findings."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"ReviewStatus":{"description":"Current processing state of a submitted document review.","type":"string","enum":["queued","processing","completed","failed"]},"DocumentReviewListResponse":{"description":"Paginated collection of reviews visible to the calling API key.","type":"object","required":["documentReviews","page"],"properties":{"documentReviews":{"type":"array","items":{"$ref":"#/components/schemas/DocumentReviewSummary"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"DocumentReviewSummary":{"description":"Summary representation of a review returned by the list endpoint.","type":"object","required":["id","status","documentId","documentEvaluationTypeId","document","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/ReviewStatus"},"documentId":{"type":"string","format":"uuid"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"document":{"$ref":"#/components/schemas/ReviewDocumentSummary"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"error":{"type":"string","description":"Failure message for reviews that completed with an error."}}},"ReviewDocumentSummary":{"description":"Summary metadata about the reviewed source document.","type":"object","required":["title","fileType"],"properties":{"title":{"type":"string","description":"Title associated with the reviewed document."},"fileType":{"type":"string","enum":["TEXT","PDF","WEBPAGE","IMAGE","WEBSITE"],"description":"Protege document type classification for the reviewed content."},"externalId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Client-provided identifier echoed back in review responses."}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/document-reviews":{"get":{"summary":"List document reviews","description":"Return document reviews visible to the authenticated tenant. This endpoint is typically used to poll or reconcile asynchronous reviews in bulk.","operationId":"listDocumentReviews","tags":["Document Reviews"],"parameters":[{"name":"id","in":"query","required":false,"description":"Filter by a specific review identifier.","schema":{"type":"string","format":"uuid"}},{"name":"documentEvaluationTypeId","in":"query","required":false,"description":"Filter reviews created with a specific document evaluation type.","schema":{"type":"string","format":"uuid"}},{"name":"externalId","in":"query","required":false,"description":"Filter by the client-supplied external document identifier.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter reviews by processing status.","schema":{"$ref":"#/components/schemas/ReviewStatus"}},{"name":"limit","in":"query","description":"Maximum number of records to return per page.","required":false,"schema":{"type":"integer","default":25}},{"name":"offset","in":"query","description":"Number of records to skip before starting the page.","required":false,"schema":{"type":"integer","default":0}},{"name":"sortBy","in":"query","description":"Field used to sort the result set.","required":false,"schema":{"type":"string","enum":["createdAt","updatedAt"],"default":"createdAt"}},{"name":"sortOrder","in":"query","description":"Sort direction for the selected sort field.","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"Document reviews page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentReviewListResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"Failed to list document reviews","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Create a document review > Submit a document for compliance review. Use JSON for plain-text content or multipart form data for file uploads. Synchronous requests return findings inline; asynchronous requests return a queued review that can be polled later. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Document Reviews","description":"Submit documents for review, track processing status, and retrieve completed findings."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"TextReviewRequest":{"description":"JSON request body for creating a review from plain text content.","type":"object","required":["documentEvaluationTypeId","document"],"properties":{"mode":{"$ref":"#/components/schemas/ReviewMode"},"documentEvaluationTypeId":{"type":"string","format":"uuid","description":"Identifier of the review configuration to apply."},"document":{"$ref":"#/components/schemas/TextReviewDocument"}}},"ReviewMode":{"description":"Controls whether the review should complete inline or be queued for background processing.","type":"string","enum":["sync","async"],"default":"sync"},"TextReviewDocument":{"description":"Plain-text document content submitted directly in the JSON request body.","type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["text"],"description":"Identifies the document payload type."},"title":{"type":"string","description":"Client-friendly document title shown in review metadata."},"externalId":{"type":"string","description":"Client-supplied identifier used to correlate Protege reviews with your own records."},"text":{"type":"string","description":"Full plain-text content to review."},"metadata":{"type":"object","description":"Optional client-defined metadata that Protege stores with the review.","additionalProperties":true}}},"MultipartFileReviewRequest":{"description":"Multipart form payload for uploading a single file to review.","type":"object","required":["documentEvaluationTypeId","file"],"properties":{"mode":{"$ref":"#/components/schemas/ReviewMode"},"documentEvaluationTypeId":{"type":"string","format":"uuid","description":"Identifier of the review configuration to apply."},"title":{"type":"string","description":"Optional title to associate with the uploaded document."},"externalId":{"type":"string","description":"Client-supplied identifier used for downstream reconciliation."},"metadata":{"type":"string","description":"JSON-encoded object string for document metadata."},"file":{"type":"string","format":"binary","description":"Upload a single file. Supported types are `.docx`, `.pdf`, `.png`, `.jpg`, and `.jpeg`.\n"}}},"CompletedReviewResponse":{"description":"Final response returned when a document review has completed successfully.","type":"object","required":["id","status","mode","documentId","documentEvaluationTypeId","document","findings"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["completed"]},"mode":{"$ref":"#/components/schemas/ReviewMode"},"documentId":{"type":"string","format":"uuid"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"document":{"$ref":"#/components/schemas/ReviewDocumentSummary"},"findings":{"type":"array","description":"Structured findings produced by the completed review.","items":{"$ref":"#/components/schemas/Finding"}}}},"ReviewDocumentSummary":{"description":"Summary metadata about the reviewed source document.","type":"object","required":["title","fileType"],"properties":{"title":{"type":"string","description":"Title associated with the reviewed document."},"fileType":{"type":"string","enum":["TEXT","PDF","WEBPAGE","IMAGE","WEBSITE"],"description":"Protege document type classification for the reviewed content."},"externalId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Client-provided identifier echoed back in review responses."}}},"Finding":{"description":"Structured review output describing a policy, trademark, or claim-related issue found in the document. The populated fields depend on the `kind` value.\n","oneOf":[{"$ref":"#/components/schemas/PolicyFeedbackFinding"},{"$ref":"#/components/schemas/ClaimFinding"},{"$ref":"#/components/schemas/TrademarkInstanceFinding"}],"discriminator":{"propertyName":"kind","mapping":{"policy_feedback":"#/components/schemas/PolicyFeedbackFinding","claim":"#/components/schemas/ClaimFinding","trademark_instance":"#/components/schemas/TrademarkInstanceFinding"}}},"PolicyFeedbackFinding":{"description":"A finding produced by a policy evaluation, such as a brand compliance violation.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["policy","details"],"properties":{"policy":{"$ref":"#/components/schemas/PolicyRef"},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Policy-specific detail payload.","properties":{"policyOutputId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the policy output that produced this finding."},"recommendation":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Actionable recommendation for resolving the finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"FindingBase":{"description":"Fields shared across every finding kind.","type":"object","required":["kind","text","comment","feedbackLocation","status","details"],"properties":{"kind":{"type":"string","enum":["policy_feedback","claim","trademark_instance"],"description":"Category of finding returned by Protege."},"text":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Text snippet or extracted value associated with the finding, when available."},"comment":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Reviewer-facing explanation of the issue or recommendation."},"riskLevel":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Severity or risk classification assigned by the review."},"feedbackLocation":{"type":"string","description":"Machine-readable indicator of the content medium where the finding was detected (e.g. 'text', 'image_ocr_text')."},"location":{"$ref":"#/components/schemas/FindingLocation"},"status":{"type":"string","description":"Resolution or approval status associated with the finding."},"approval":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Approval guidance for trademark-related findings, when applicable."},"metadata":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"Additional model-specific or workflow-specific metadata."},"formattedOutput":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Richly formatted version of the finding when available."}}},"FindingLocation":{"description":"Location metadata for a finding within a document.","type":"object","required":["pageNumber"],"properties":{"pageNumber":{"type":"integer"}}},"PolicyRef":{"description":"Lightweight policy reference attached to a finding.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"TrademarkRef":{"description":"Lightweight trademark reference attached to a finding.","type":"object","required":["id","name","proprietary"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"proprietary":{"type":"boolean"},"approval":{"oneOf":[{"type":"string"},{"type":"null"}]},"markType":{"oneOf":[{"type":"string"},{"type":"null"}]}}},"ClaimFinding":{"description":"A finding representing an extracted claim, such as a marketing guarantee or warranty statement.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Claim-specific detail payload.","properties":{"claim":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Canonical claim text extracted from the document."},"disclosureText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Recommended disclosure or qualifying text for a claim finding."},"userFixedText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"User-provided replacement text for a claim finding."},"approvalLimitations":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Scope or limitations tied to an approved claim finding."},"approvalExpireAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Expiration timestamp for an approved claim finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"TrademarkInstanceFinding":{"description":"A finding representing a potential trademark usage issue detected in the document.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["trademark","details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"$ref":"#/components/schemas/TrademarkRef"},"details":{"type":"object","description":"Trademark-specific detail payload.","properties":{"suggestedFixCasing":{"type":"boolean","description":"Whether the trademark instance suggests a casing fix."},"recommendedMarkType":{"type":"string","description":"Recommended mark type for a trademark instance (e.g. 'trademark', 'registered')."},"suggestedMarkExplanation":{"type":"string","description":"Explanation for the recommended mark type."},"suggestedMarkRecord":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"USPTO record details when a trademark match is found.","properties":{"keyword":{"type":"string"},"registrationNumber":{"type":"string"},"registrationDate":{"type":"string"},"statusLabel":{"type":"string"},"ownerName":{"type":"string"},"logo":{"type":"string","format":"uri"}}}}}}}]},"PendingReviewResponse":{"description":"Review response returned while an asynchronous review is still queued, processing, or has failed.","type":"object","required":["id","status","mode","documentId","documentEvaluationTypeId","document","findings"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","processing","failed"]},"mode":{"type":"string","enum":["async"]},"documentId":{"type":"string","format":"uuid"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"document":{"$ref":"#/components/schemas/ReviewDocumentSummary"},"findings":{"type":"array","description":"Findings accumulated so far. This is typically empty until processing finishes.","items":{"$ref":"#/components/schemas/Finding"}},"error":{"type":"string","description":"Failure message when the asynchronous review ends in a `failed` state."}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/document-reviews":{"post":{"summary":"Create a document review","description":"Submit a document for compliance review. Use JSON for plain-text content or multipart form data for file uploads. Synchronous requests return findings inline; asynchronous requests return a queued review that can be polled later.","operationId":"createDocumentReview","tags":["Document Reviews"],"requestBody":{"required":true,"description":"Review request body supplied as JSON or multipart form data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TextReviewRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/MultipartFileReviewRequest"},"encoding":{"metadata":{"contentType":"text/plain"}}}}},"responses":{"200":{"description":"Sync review completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletedReviewResponse"}}}},"202":{"description":"Async review accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingReviewResponse"}}}},"400":{"description":"Validation or sync-limit error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Document evaluation type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Unsupported content type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` ## Get document review status or result > Retrieve the latest state of a specific document review. Completed reviews include findings; pending reviews expose queue or processing status. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Document Reviews","description":"Submit documents for review, track processing status, and retrieve completed findings."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"CompletedReviewResponse":{"description":"Final response returned when a document review has completed successfully.","type":"object","required":["id","status","mode","documentId","documentEvaluationTypeId","document","findings"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["completed"]},"mode":{"$ref":"#/components/schemas/ReviewMode"},"documentId":{"type":"string","format":"uuid"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"document":{"$ref":"#/components/schemas/ReviewDocumentSummary"},"findings":{"type":"array","description":"Structured findings produced by the completed review.","items":{"$ref":"#/components/schemas/Finding"}}}},"ReviewMode":{"description":"Controls whether the review should complete inline or be queued for background processing.","type":"string","enum":["sync","async"],"default":"sync"},"ReviewDocumentSummary":{"description":"Summary metadata about the reviewed source document.","type":"object","required":["title","fileType"],"properties":{"title":{"type":"string","description":"Title associated with the reviewed document."},"fileType":{"type":"string","enum":["TEXT","PDF","WEBPAGE","IMAGE","WEBSITE"],"description":"Protege document type classification for the reviewed content."},"externalId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Client-provided identifier echoed back in review responses."}}},"Finding":{"description":"Structured review output describing a policy, trademark, or claim-related issue found in the document. The populated fields depend on the `kind` value.\n","oneOf":[{"$ref":"#/components/schemas/PolicyFeedbackFinding"},{"$ref":"#/components/schemas/ClaimFinding"},{"$ref":"#/components/schemas/TrademarkInstanceFinding"}],"discriminator":{"propertyName":"kind","mapping":{"policy_feedback":"#/components/schemas/PolicyFeedbackFinding","claim":"#/components/schemas/ClaimFinding","trademark_instance":"#/components/schemas/TrademarkInstanceFinding"}}},"PolicyFeedbackFinding":{"description":"A finding produced by a policy evaluation, such as a brand compliance violation.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["policy","details"],"properties":{"policy":{"$ref":"#/components/schemas/PolicyRef"},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Policy-specific detail payload.","properties":{"policyOutputId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the policy output that produced this finding."},"recommendation":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Actionable recommendation for resolving the finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"FindingBase":{"description":"Fields shared across every finding kind.","type":"object","required":["kind","text","comment","feedbackLocation","status","details"],"properties":{"kind":{"type":"string","enum":["policy_feedback","claim","trademark_instance"],"description":"Category of finding returned by Protege."},"text":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Text snippet or extracted value associated with the finding, when available."},"comment":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Reviewer-facing explanation of the issue or recommendation."},"riskLevel":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Severity or risk classification assigned by the review."},"feedbackLocation":{"type":"string","description":"Machine-readable indicator of the content medium where the finding was detected (e.g. 'text', 'image_ocr_text')."},"location":{"$ref":"#/components/schemas/FindingLocation"},"status":{"type":"string","description":"Resolution or approval status associated with the finding."},"approval":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Approval guidance for trademark-related findings, when applicable."},"metadata":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"Additional model-specific or workflow-specific metadata."},"formattedOutput":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Richly formatted version of the finding when available."}}},"FindingLocation":{"description":"Location metadata for a finding within a document.","type":"object","required":["pageNumber"],"properties":{"pageNumber":{"type":"integer"}}},"PolicyRef":{"description":"Lightweight policy reference attached to a finding.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"TrademarkRef":{"description":"Lightweight trademark reference attached to a finding.","type":"object","required":["id","name","proprietary"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"proprietary":{"type":"boolean"},"approval":{"oneOf":[{"type":"string"},{"type":"null"}]},"markType":{"oneOf":[{"type":"string"},{"type":"null"}]}}},"ClaimFinding":{"description":"A finding representing an extracted claim, such as a marketing guarantee or warranty statement.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Claim-specific detail payload.","properties":{"claim":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Canonical claim text extracted from the document."},"disclosureText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Recommended disclosure or qualifying text for a claim finding."},"userFixedText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"User-provided replacement text for a claim finding."},"approvalLimitations":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Scope or limitations tied to an approved claim finding."},"approvalExpireAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Expiration timestamp for an approved claim finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"TrademarkInstanceFinding":{"description":"A finding representing a potential trademark usage issue detected in the document.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["trademark","details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"$ref":"#/components/schemas/TrademarkRef"},"details":{"type":"object","description":"Trademark-specific detail payload.","properties":{"suggestedFixCasing":{"type":"boolean","description":"Whether the trademark instance suggests a casing fix."},"recommendedMarkType":{"type":"string","description":"Recommended mark type for a trademark instance (e.g. 'trademark', 'registered')."},"suggestedMarkExplanation":{"type":"string","description":"Explanation for the recommended mark type."},"suggestedMarkRecord":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"USPTO record details when a trademark match is found.","properties":{"keyword":{"type":"string"},"registrationNumber":{"type":"string"},"registrationDate":{"type":"string"},"statusLabel":{"type":"string"},"ownerName":{"type":"string"},"logo":{"type":"string","format":"uri"}}}}}}}]},"PendingReviewResponse":{"description":"Review response returned while an asynchronous review is still queued, processing, or has failed.","type":"object","required":["id","status","mode","documentId","documentEvaluationTypeId","document","findings"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","processing","failed"]},"mode":{"type":"string","enum":["async"]},"documentId":{"type":"string","format":"uuid"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"document":{"$ref":"#/components/schemas/ReviewDocumentSummary"},"findings":{"type":"array","description":"Findings accumulated so far. This is typically empty until processing finishes.","items":{"$ref":"#/components/schemas/Finding"}},"error":{"type":"string","description":"Failure message when the asynchronous review ends in a `failed` state."}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/document-reviews/{reviewId}":{"get":{"summary":"Get document review status or result","description":"Retrieve the latest state of a specific document review. Completed reviews include findings; pending reviews expose queue or processing status.","operationId":"getDocumentReview","tags":["Document Reviews"],"parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Review status or completed result","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CompletedReviewResponse"},{"$ref":"#/components/schemas/PendingReviewResponse"}]}}}},"400":{"description":"Missing review id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Review not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` # Scanner Jobs Configure ongoing website monitoring jobs and inspect their latest run history. ## List scanner jobs > Return the scanner jobs owned by the authenticated tenant, including their most recent run when available. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Scanner Jobs","description":"Configure ongoing website monitoring jobs and inspect their latest run history."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"ScannerJobListResponse":{"description":"Paginated collection of scanner jobs.","type":"object","required":["scannerJobs","page"],"properties":{"scannerJobs":{"type":"array","items":{"$ref":"#/components/schemas/ScannerJob"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"ScannerJob":{"description":"Scanner job summary returned by list and create operations.","type":"object","required":["id","urls"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"oneOf":[{"type":"string"},{"type":"null"}]},"urls":{"type":"array","items":{"type":"string","format":"uri"}},"scheduler":{"oneOf":[{"type":"string"},{"type":"null"}]},"brand":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobBrand"},{"type":"null"}]},"documentEvaluationType":{"$ref":"#/components/schemas/ScannerJobDocumentEvaluationType"},"lastRun":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobRunSummary"},{"type":"null"}]}}},"ScannerJobBrand":{"description":"Brand assigned to a scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobDocumentEvaluationType":{"description":"Review configuration applied to content discovered by the scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobRunSummary":{"description":"High-level status for a single execution of a scanner job.","type":"object","required":["id","status","scheduledTime","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CREATED","RUNNING","FINISHED","FAILED"]},"scheduledTime":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/scanner-jobs":{"get":{"summary":"List scanner jobs","description":"Return the scanner jobs owned by the authenticated tenant, including their most recent run when available.","operationId":"listScannerJobs","tags":["Scanner Jobs"],"parameters":[{"name":"id","in":"query","description":"Filter by a specific scanner job identifier.","schema":{"type":"string","format":"uuid"}},{"name":"brandId","in":"query","description":"Filter jobs assigned to a specific brand.","schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Case-insensitive search against scanner job names.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of records to return per page.","schema":{"type":"integer","minimum":1,"default":25}},{"name":"offset","in":"query","description":"Number of records to skip before starting the page.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"sortBy","in":"query","description":"Field used to sort the result set.","schema":{"type":"string","enum":["createdAt","name"]}},{"name":"sortOrder","in":"query","description":"Sort direction for the selected sort field.","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Scanner jobs returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScannerJobListResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` ## Create a content scanner job > Create a new website monitoring job that crawls the provided URLs and evaluates discovered content using the selected document evaluation type. The crawl engine is selected automatically based on the evaluation type's useCase. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Scanner Jobs","description":"Configure ongoing website monitoring jobs and inspect their latest run history."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"ScannerJobCreateRequest":{"description":"Request body used to create a new scanner job.","type":"object","required":["name","documentEvaluationTypeId","urls"],"properties":{"name":{"type":"string"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"urls":{"type":"array","items":{"type":"string","format":"uri"}},"scheduler":{"type":"string"},"maxPages":{"type":"integer"},"maxDepth":{"type":"integer"},"maxTrackedPages":{"type":"integer","minimum":1},"newPagesForSuccessiveScans":{"type":"integer","minimum":0},"brandId":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"showAllFeedbackInDecisionStore":{"type":"boolean"},"translationEnabled":{"type":"boolean"},"useSitemaps":{"type":"boolean"},"archiveMode":{"oneOf":[{"type":"string","enum":["ON_FOR_ALL","ON_FOR_BRAND_MENTIONED"]},{"type":"null"}]}}},"ScannerJobCreateResponse":{"description":"Wrapper returned after a scanner job is created successfully.","type":"object","required":["scannerJob"],"properties":{"scannerJob":{"$ref":"#/components/schemas/ScannerJob"}}},"ScannerJob":{"description":"Scanner job summary returned by list and create operations.","type":"object","required":["id","urls"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"oneOf":[{"type":"string"},{"type":"null"}]},"urls":{"type":"array","items":{"type":"string","format":"uri"}},"scheduler":{"oneOf":[{"type":"string"},{"type":"null"}]},"brand":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobBrand"},{"type":"null"}]},"documentEvaluationType":{"$ref":"#/components/schemas/ScannerJobDocumentEvaluationType"},"lastRun":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobRunSummary"},{"type":"null"}]}}},"ScannerJobBrand":{"description":"Brand assigned to a scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobDocumentEvaluationType":{"description":"Review configuration applied to content discovered by the scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobRunSummary":{"description":"High-level status for a single execution of a scanner job.","type":"object","required":["id","status","scheduledTime","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CREATED","RUNNING","FINISHED","FAILED"]},"scheduledTime":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/scanner-jobs":{"post":{"summary":"Create a content scanner job","description":"Create a new website monitoring job that crawls the provided URLs and evaluates discovered content using the selected document evaluation type. The crawl engine is selected automatically based on the evaluation type's useCase.","operationId":"createScannerJob","tags":["Scanner Jobs"],"requestBody":{"required":true,"description":"Scanner job configuration, including crawl targets, schedule, and review settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScannerJobCreateRequest"}}}},"responses":{"201":{"description":"Scanner job created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScannerJobCreateResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Related evaluation type or brand not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` ## Get a scanner job > Retrieve the full configuration and latest run summary for a single scanner job. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Scanner Jobs","description":"Configure ongoing website monitoring jobs and inspect their latest run history."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"ScannerJobDetailResponse":{"description":"Wrapper containing a single scanner job record.","type":"object","required":["scannerJob"],"properties":{"scannerJob":{"$ref":"#/components/schemas/ScannerJobDetail"}}},"ScannerJobDetail":{"description":"Full scanner job configuration, including crawl and archival options.","allOf":[{"$ref":"#/components/schemas/ScannerJob"},{"type":"object","required":["showAllFeedbackInDecisionStore","translationEnabled"],"properties":{"maxPages":{"oneOf":[{"type":"integer"},{"type":"null"}]},"maxDepth":{"oneOf":[{"type":"integer"},{"type":"null"}]},"maxTrackedPages":{"oneOf":[{"type":"integer"},{"type":"null"}]},"newPagesForSuccessiveScans":{"oneOf":[{"type":"integer"},{"type":"null"}]},"showAllFeedbackInDecisionStore":{"type":"boolean"},"translationEnabled":{"type":"boolean"},"useSitemaps":{"oneOf":[{"type":"boolean"},{"type":"null"}]},"archiveMode":{"oneOf":[{"type":"string","enum":["ON_FOR_ALL","ON_FOR_BRAND_MENTIONED"]},{"type":"null"}]}}}]},"ScannerJob":{"description":"Scanner job summary returned by list and create operations.","type":"object","required":["id","urls"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"oneOf":[{"type":"string"},{"type":"null"}]},"urls":{"type":"array","items":{"type":"string","format":"uri"}},"scheduler":{"oneOf":[{"type":"string"},{"type":"null"}]},"brand":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobBrand"},{"type":"null"}]},"documentEvaluationType":{"$ref":"#/components/schemas/ScannerJobDocumentEvaluationType"},"lastRun":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobRunSummary"},{"type":"null"}]}}},"ScannerJobBrand":{"description":"Brand assigned to a scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobDocumentEvaluationType":{"description":"Review configuration applied to content discovered by the scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobRunSummary":{"description":"High-level status for a single execution of a scanner job.","type":"object","required":["id","status","scheduledTime","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CREATED","RUNNING","FINISHED","FAILED"]},"scheduledTime":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/scanner-jobs/{scannerJobId}":{"get":{"summary":"Get a scanner job","description":"Retrieve the full configuration and latest run summary for a single scanner job.","operationId":"getScannerJob","tags":["Scanner Jobs"],"parameters":[{"name":"scannerJobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Scanner job returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScannerJobDetailResponse"}}}},"400":{"description":"Missing or invalid scanner job id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Scanner job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` ## Delete a scanner job > Permanently delete a scanner job so it no longer runs or appears in list results. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Scanner Jobs","description":"Configure ongoing website monitoring jobs and inspect their latest run history."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/scanner-jobs/{scannerJobId}":{"delete":{"summary":"Delete a scanner job","description":"Permanently delete a scanner job so it no longer runs or appears in list results.","operationId":"deleteScannerJob","tags":["Scanner Jobs"],"parameters":[{"name":"scannerJobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Scanner job deleted"},"400":{"description":"Missing or invalid scanner job id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Scanner job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` ## Update a scanner job > Partially update an existing scanner job. Only the fields supplied in the request body are modified. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Scanner Jobs","description":"Configure ongoing website monitoring jobs and inspect their latest run history."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"ScannerJobUpdateRequest":{"description":"Partial update payload for a scanner job. Include only the fields you want to change.","type":"object","minProperties":1,"properties":{"name":{"type":"string"},"urls":{"type":"array","minItems":1,"items":{"type":"string","format":"uri"}},"scheduler":{"oneOf":[{"type":"string"},{"type":"null"}]},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"brandId":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"maxPages":{"type":"integer"},"maxDepth":{"type":"integer"},"maxTrackedPages":{"type":"integer","minimum":1},"newPagesForSuccessiveScans":{"type":"integer","minimum":0},"showAllFeedbackInDecisionStore":{"type":"boolean"},"translationEnabled":{"type":"boolean"},"useSitemaps":{"type":"boolean"},"archiveMode":{"oneOf":[{"type":"string","enum":["ON_FOR_ALL","ON_FOR_BRAND_MENTIONED"]},{"type":"null"}]}}},"ScannerJobDetailResponse":{"description":"Wrapper containing a single scanner job record.","type":"object","required":["scannerJob"],"properties":{"scannerJob":{"$ref":"#/components/schemas/ScannerJobDetail"}}},"ScannerJobDetail":{"description":"Full scanner job configuration, including crawl and archival options.","allOf":[{"$ref":"#/components/schemas/ScannerJob"},{"type":"object","required":["showAllFeedbackInDecisionStore","translationEnabled"],"properties":{"maxPages":{"oneOf":[{"type":"integer"},{"type":"null"}]},"maxDepth":{"oneOf":[{"type":"integer"},{"type":"null"}]},"maxTrackedPages":{"oneOf":[{"type":"integer"},{"type":"null"}]},"newPagesForSuccessiveScans":{"oneOf":[{"type":"integer"},{"type":"null"}]},"showAllFeedbackInDecisionStore":{"type":"boolean"},"translationEnabled":{"type":"boolean"},"useSitemaps":{"oneOf":[{"type":"boolean"},{"type":"null"}]},"archiveMode":{"oneOf":[{"type":"string","enum":["ON_FOR_ALL","ON_FOR_BRAND_MENTIONED"]},{"type":"null"}]}}}]},"ScannerJob":{"description":"Scanner job summary returned by list and create operations.","type":"object","required":["id","urls"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"oneOf":[{"type":"string"},{"type":"null"}]},"urls":{"type":"array","items":{"type":"string","format":"uri"}},"scheduler":{"oneOf":[{"type":"string"},{"type":"null"}]},"brand":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobBrand"},{"type":"null"}]},"documentEvaluationType":{"$ref":"#/components/schemas/ScannerJobDocumentEvaluationType"},"lastRun":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobRunSummary"},{"type":"null"}]}}},"ScannerJobBrand":{"description":"Brand assigned to a scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobDocumentEvaluationType":{"description":"Review configuration applied to content discovered by the scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobRunSummary":{"description":"High-level status for a single execution of a scanner job.","type":"object","required":["id","status","scheduledTime","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CREATED","RUNNING","FINISHED","FAILED"]},"scheduledTime":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/scanner-jobs/{scannerJobId}":{"patch":{"summary":"Update a scanner job","description":"Partially update an existing scanner job. Only the fields supplied in the request body are modified.","operationId":"updateScannerJob","tags":["Scanner Jobs"],"parameters":[{"name":"scannerJobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"description":"Partial scanner job update payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScannerJobUpdateRequest"}}}},"responses":{"200":{"description":"Scanner job updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScannerJobDetailResponse"}}}},"400":{"description":"Invalid scanner job id or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Scanner job or related brand/evaluation type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` ## List scanner job runs > Return historical executions for a scanner job, ordered by most recent first. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Scanner Jobs","description":"Configure ongoing website monitoring jobs and inspect their latest run history."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"ScannerJobRunsResponse":{"description":"Paginated collection of historical runs for a scanner job.","type":"object","required":["scannerRuns","page"],"properties":{"scannerRuns":{"type":"array","items":{"$ref":"#/components/schemas/ScannerJobRun"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"ScannerJobRun":{"description":"Detailed execution metadata for a scanner job run.","allOf":[{"$ref":"#/components/schemas/ScannerJobRunSummary"},{"type":"object","required":["updatedAt"],"properties":{"updatedAt":{"type":"string","format":"date-time"}}}]},"ScannerJobRunSummary":{"description":"High-level status for a single execution of a scanner job.","type":"object","required":["id","status","scheduledTime","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CREATED","RUNNING","FINISHED","FAILED"]},"scheduledTime":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/scanner-jobs/{scannerJobId}/runs":{"get":{"summary":"List scanner job runs","description":"Return historical executions for a scanner job, ordered by most recent first.","operationId":"listScannerJobRuns","tags":["Scanner Jobs"],"parameters":[{"name":"scannerJobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Maximum number of records to return per page.","schema":{"type":"integer","minimum":1,"default":25}},{"name":"offset","in":"query","description":"Number of records to skip before starting the page.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Scanner job runs returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScannerJobRunsResponse"}}}},"400":{"description":"Missing or invalid scanner job id or query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Scanner job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` # Reports Retrieve scanner report summaries and detailed page-level report output. ## List reports > Return scanner report summaries generated from completed scanner runs. Reports can be filtered by brand or searched by name. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Reports","description":"Retrieve scanner report summaries and detailed page-level report output."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"ReportListResponse":{"description":"Paginated collection of scanner reports.","type":"object","required":["reports","page"],"properties":{"reports":{"type":"array","items":{"$ref":"#/components/schemas/ReportListItem"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"ReportListItem":{"description":"Summary representation of a scanner report.","type":"object","required":["id","name","createdAt","documentCount"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"brand":{"oneOf":[{"$ref":"#/components/schemas/ReportBrand"},{"type":"null"}]},"documentCount":{"type":"integer"}}},"ReportBrand":{"description":"Lightweight brand reference attached to a scanner report.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/reports":{"get":{"summary":"List reports","description":"Return scanner report summaries generated from completed scanner runs. Reports can be filtered by brand or searched by name.","operationId":"listReports","tags":["Reports"],"parameters":[{"name":"brandId","in":"query","description":"Filter reports for a specific brand.","schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Case-insensitive search against report names.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of records to return per page.","schema":{"type":"integer","minimum":1,"default":25}},{"name":"offset","in":"query","description":"Number of records to skip before starting the page.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"sortBy","in":"query","description":"Field used to sort the result set.","schema":{"type":"string","enum":["createdAt","name","documentCount"]}},{"name":"sortOrder","in":"query","description":"Sort direction for the selected sort field.","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Report summaries returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportListResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` ## Get a report with scanned pages > Retrieve a report and the scanned pages or captured documents that make up the report payload. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Reports","description":"Retrieve scanner report summaries and detailed page-level report output."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"ReportDetail":{"description":"Report detail including captured pages and page-level metadata.","allOf":[{"$ref":"#/components/schemas/ReportDetailSummary"},{"type":"object","required":["pages"],"properties":{"pages":{"type":"array","items":{"$ref":"#/components/schemas/ReportPage"}}}}]},"ReportDetailSummary":{"description":"Top-level report metadata returned with detailed report responses.","type":"object","required":["id","name","createdAt","documentCount"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"brand":{"oneOf":[{"$ref":"#/components/schemas/ReportBrand"},{"type":"null"}]},"documentCount":{"type":"integer"}}},"ReportBrand":{"description":"Lightweight brand reference attached to a scanner report.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ReportPage":{"description":"Page or document captured within a scanner report.","type":"object","required":["documentId","title","fileType","createdAt"],"properties":{"documentId":{"type":"string","format":"uuid"},"title":{"type":"string"},"link":{"oneOf":[{"type":"string"},{"type":"null"}]},"fileType":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"lastScannedAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/reports/{reportId}":{"get":{"summary":"Get a report with scanned pages","description":"Retrieve a report and the scanned pages or captured documents that make up the report payload.","operationId":"getReport","tags":["Reports"],"parameters":[{"name":"reportId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Report detail returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportDetail"}}}},"400":{"description":"Missing or invalid report id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Report not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` # Models ## The ErrorResponse object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}}}}} ``` ## The ReviewMode object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ReviewMode":{"description":"Controls whether the review should complete inline or be queued for background processing.","type":"string","enum":["sync","async"],"default":"sync"}}}} ``` ## The ReviewStatus object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ReviewStatus":{"description":"Current processing state of a submitted document review.","type":"string","enum":["queued","processing","completed","failed"]}}}} ``` ## The TextReviewDocument object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"TextReviewDocument":{"description":"Plain-text document content submitted directly in the JSON request body.","type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["text"],"description":"Identifies the document payload type."},"title":{"type":"string","description":"Client-friendly document title shown in review metadata."},"externalId":{"type":"string","description":"Client-supplied identifier used to correlate Protege reviews with your own records."},"text":{"type":"string","description":"Full plain-text content to review."},"metadata":{"type":"object","description":"Optional client-defined metadata that Protege stores with the review.","additionalProperties":true}}}}}} ``` ## The TextReviewRequest object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"TextReviewRequest":{"description":"JSON request body for creating a review from plain text content.","type":"object","required":["documentEvaluationTypeId","document"],"properties":{"mode":{"$ref":"#/components/schemas/ReviewMode"},"documentEvaluationTypeId":{"type":"string","format":"uuid","description":"Identifier of the review configuration to apply."},"document":{"$ref":"#/components/schemas/TextReviewDocument"}}},"ReviewMode":{"description":"Controls whether the review should complete inline or be queued for background processing.","type":"string","enum":["sync","async"],"default":"sync"},"TextReviewDocument":{"description":"Plain-text document content submitted directly in the JSON request body.","type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["text"],"description":"Identifies the document payload type."},"title":{"type":"string","description":"Client-friendly document title shown in review metadata."},"externalId":{"type":"string","description":"Client-supplied identifier used to correlate Protege reviews with your own records."},"text":{"type":"string","description":"Full plain-text content to review."},"metadata":{"type":"object","description":"Optional client-defined metadata that Protege stores with the review.","additionalProperties":true}}}}}} ``` ## The MultipartFileReviewRequest object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"MultipartFileReviewRequest":{"description":"Multipart form payload for uploading a single file to review.","type":"object","required":["documentEvaluationTypeId","file"],"properties":{"mode":{"$ref":"#/components/schemas/ReviewMode"},"documentEvaluationTypeId":{"type":"string","format":"uuid","description":"Identifier of the review configuration to apply."},"title":{"type":"string","description":"Optional title to associate with the uploaded document."},"externalId":{"type":"string","description":"Client-supplied identifier used for downstream reconciliation."},"metadata":{"type":"string","description":"JSON-encoded object string for document metadata."},"file":{"type":"string","format":"binary","description":"Upload a single file. Supported types are `.docx`, `.pdf`, `.png`, `.jpg`, and `.jpeg`.\n"}}},"ReviewMode":{"description":"Controls whether the review should complete inline or be queued for background processing.","type":"string","enum":["sync","async"],"default":"sync"}}}} ``` ## The PolicyRef object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"PolicyRef":{"description":"Lightweight policy reference attached to a finding.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}} ``` ## The TrademarkRef object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"TrademarkRef":{"description":"Lightweight trademark reference attached to a finding.","type":"object","required":["id","name","proprietary"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"proprietary":{"type":"boolean"},"approval":{"oneOf":[{"type":"string"},{"type":"null"}]},"markType":{"oneOf":[{"type":"string"},{"type":"null"}]}}}}}} ``` ## The Finding object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"Finding":{"description":"Structured review output describing a policy, trademark, or claim-related issue found in the document. The populated fields depend on the `kind` value.\n","oneOf":[{"$ref":"#/components/schemas/PolicyFeedbackFinding"},{"$ref":"#/components/schemas/ClaimFinding"},{"$ref":"#/components/schemas/TrademarkInstanceFinding"}],"discriminator":{"propertyName":"kind","mapping":{"policy_feedback":"#/components/schemas/PolicyFeedbackFinding","claim":"#/components/schemas/ClaimFinding","trademark_instance":"#/components/schemas/TrademarkInstanceFinding"}}},"PolicyFeedbackFinding":{"description":"A finding produced by a policy evaluation, such as a brand compliance violation.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["policy","details"],"properties":{"policy":{"$ref":"#/components/schemas/PolicyRef"},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Policy-specific detail payload.","properties":{"policyOutputId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the policy output that produced this finding."},"recommendation":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Actionable recommendation for resolving the finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"FindingBase":{"description":"Fields shared across every finding kind.","type":"object","required":["kind","text","comment","feedbackLocation","status","details"],"properties":{"kind":{"type":"string","enum":["policy_feedback","claim","trademark_instance"],"description":"Category of finding returned by Protege."},"text":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Text snippet or extracted value associated with the finding, when available."},"comment":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Reviewer-facing explanation of the issue or recommendation."},"riskLevel":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Severity or risk classification assigned by the review."},"feedbackLocation":{"type":"string","description":"Machine-readable indicator of the content medium where the finding was detected (e.g. 'text', 'image_ocr_text')."},"location":{"$ref":"#/components/schemas/FindingLocation"},"status":{"type":"string","description":"Resolution or approval status associated with the finding."},"approval":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Approval guidance for trademark-related findings, when applicable."},"metadata":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"Additional model-specific or workflow-specific metadata."},"formattedOutput":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Richly formatted version of the finding when available."}}},"FindingLocation":{"description":"Location metadata for a finding within a document.","type":"object","required":["pageNumber"],"properties":{"pageNumber":{"type":"integer"}}},"PolicyRef":{"description":"Lightweight policy reference attached to a finding.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"TrademarkRef":{"description":"Lightweight trademark reference attached to a finding.","type":"object","required":["id","name","proprietary"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"proprietary":{"type":"boolean"},"approval":{"oneOf":[{"type":"string"},{"type":"null"}]},"markType":{"oneOf":[{"type":"string"},{"type":"null"}]}}},"ClaimFinding":{"description":"A finding representing an extracted claim, such as a marketing guarantee or warranty statement.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Claim-specific detail payload.","properties":{"claim":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Canonical claim text extracted from the document."},"disclosureText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Recommended disclosure or qualifying text for a claim finding."},"userFixedText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"User-provided replacement text for a claim finding."},"approvalLimitations":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Scope or limitations tied to an approved claim finding."},"approvalExpireAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Expiration timestamp for an approved claim finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"TrademarkInstanceFinding":{"description":"A finding representing a potential trademark usage issue detected in the document.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["trademark","details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"$ref":"#/components/schemas/TrademarkRef"},"details":{"type":"object","description":"Trademark-specific detail payload.","properties":{"suggestedFixCasing":{"type":"boolean","description":"Whether the trademark instance suggests a casing fix."},"recommendedMarkType":{"type":"string","description":"Recommended mark type for a trademark instance (e.g. 'trademark', 'registered')."},"suggestedMarkExplanation":{"type":"string","description":"Explanation for the recommended mark type."},"suggestedMarkRecord":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"USPTO record details when a trademark match is found.","properties":{"keyword":{"type":"string"},"registrationNumber":{"type":"string"},"registrationDate":{"type":"string"},"statusLabel":{"type":"string"},"ownerName":{"type":"string"},"logo":{"type":"string","format":"uri"}}}}}}}]}}}} ``` ## The FindingBase object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"FindingBase":{"description":"Fields shared across every finding kind.","type":"object","required":["kind","text","comment","feedbackLocation","status","details"],"properties":{"kind":{"type":"string","enum":["policy_feedback","claim","trademark_instance"],"description":"Category of finding returned by Protege."},"text":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Text snippet or extracted value associated with the finding, when available."},"comment":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Reviewer-facing explanation of the issue or recommendation."},"riskLevel":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Severity or risk classification assigned by the review."},"feedbackLocation":{"type":"string","description":"Machine-readable indicator of the content medium where the finding was detected (e.g. 'text', 'image_ocr_text')."},"location":{"$ref":"#/components/schemas/FindingLocation"},"status":{"type":"string","description":"Resolution or approval status associated with the finding."},"approval":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Approval guidance for trademark-related findings, when applicable."},"metadata":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"Additional model-specific or workflow-specific metadata."},"formattedOutput":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Richly formatted version of the finding when available."}}},"FindingLocation":{"description":"Location metadata for a finding within a document.","type":"object","required":["pageNumber"],"properties":{"pageNumber":{"type":"integer"}}}}}} ``` ## The FindingLocation object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"FindingLocation":{"description":"Location metadata for a finding within a document.","type":"object","required":["pageNumber"],"properties":{"pageNumber":{"type":"integer"}}}}}} ``` ## The PolicyFeedbackFinding object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"PolicyFeedbackFinding":{"description":"A finding produced by a policy evaluation, such as a brand compliance violation.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["policy","details"],"properties":{"policy":{"$ref":"#/components/schemas/PolicyRef"},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Policy-specific detail payload.","properties":{"policyOutputId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the policy output that produced this finding."},"recommendation":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Actionable recommendation for resolving the finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"FindingBase":{"description":"Fields shared across every finding kind.","type":"object","required":["kind","text","comment","feedbackLocation","status","details"],"properties":{"kind":{"type":"string","enum":["policy_feedback","claim","trademark_instance"],"description":"Category of finding returned by Protege."},"text":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Text snippet or extracted value associated with the finding, when available."},"comment":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Reviewer-facing explanation of the issue or recommendation."},"riskLevel":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Severity or risk classification assigned by the review."},"feedbackLocation":{"type":"string","description":"Machine-readable indicator of the content medium where the finding was detected (e.g. 'text', 'image_ocr_text')."},"location":{"$ref":"#/components/schemas/FindingLocation"},"status":{"type":"string","description":"Resolution or approval status associated with the finding."},"approval":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Approval guidance for trademark-related findings, when applicable."},"metadata":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"Additional model-specific or workflow-specific metadata."},"formattedOutput":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Richly formatted version of the finding when available."}}},"FindingLocation":{"description":"Location metadata for a finding within a document.","type":"object","required":["pageNumber"],"properties":{"pageNumber":{"type":"integer"}}},"PolicyRef":{"description":"Lightweight policy reference attached to a finding.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"TrademarkRef":{"description":"Lightweight trademark reference attached to a finding.","type":"object","required":["id","name","proprietary"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"proprietary":{"type":"boolean"},"approval":{"oneOf":[{"type":"string"},{"type":"null"}]},"markType":{"oneOf":[{"type":"string"},{"type":"null"}]}}}}}} ``` ## The ClaimFinding object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ClaimFinding":{"description":"A finding representing an extracted claim, such as a marketing guarantee or warranty statement.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Claim-specific detail payload.","properties":{"claim":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Canonical claim text extracted from the document."},"disclosureText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Recommended disclosure or qualifying text for a claim finding."},"userFixedText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"User-provided replacement text for a claim finding."},"approvalLimitations":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Scope or limitations tied to an approved claim finding."},"approvalExpireAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Expiration timestamp for an approved claim finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"FindingBase":{"description":"Fields shared across every finding kind.","type":"object","required":["kind","text","comment","feedbackLocation","status","details"],"properties":{"kind":{"type":"string","enum":["policy_feedback","claim","trademark_instance"],"description":"Category of finding returned by Protege."},"text":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Text snippet or extracted value associated with the finding, when available."},"comment":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Reviewer-facing explanation of the issue or recommendation."},"riskLevel":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Severity or risk classification assigned by the review."},"feedbackLocation":{"type":"string","description":"Machine-readable indicator of the content medium where the finding was detected (e.g. 'text', 'image_ocr_text')."},"location":{"$ref":"#/components/schemas/FindingLocation"},"status":{"type":"string","description":"Resolution or approval status associated with the finding."},"approval":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Approval guidance for trademark-related findings, when applicable."},"metadata":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"Additional model-specific or workflow-specific metadata."},"formattedOutput":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Richly formatted version of the finding when available."}}},"FindingLocation":{"description":"Location metadata for a finding within a document.","type":"object","required":["pageNumber"],"properties":{"pageNumber":{"type":"integer"}}},"PolicyRef":{"description":"Lightweight policy reference attached to a finding.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"TrademarkRef":{"description":"Lightweight trademark reference attached to a finding.","type":"object","required":["id","name","proprietary"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"proprietary":{"type":"boolean"},"approval":{"oneOf":[{"type":"string"},{"type":"null"}]},"markType":{"oneOf":[{"type":"string"},{"type":"null"}]}}}}}} ``` ## The TrademarkInstanceFinding object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"TrademarkInstanceFinding":{"description":"A finding representing a potential trademark usage issue detected in the document.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["trademark","details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"$ref":"#/components/schemas/TrademarkRef"},"details":{"type":"object","description":"Trademark-specific detail payload.","properties":{"suggestedFixCasing":{"type":"boolean","description":"Whether the trademark instance suggests a casing fix."},"recommendedMarkType":{"type":"string","description":"Recommended mark type for a trademark instance (e.g. 'trademark', 'registered')."},"suggestedMarkExplanation":{"type":"string","description":"Explanation for the recommended mark type."},"suggestedMarkRecord":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"USPTO record details when a trademark match is found.","properties":{"keyword":{"type":"string"},"registrationNumber":{"type":"string"},"registrationDate":{"type":"string"},"statusLabel":{"type":"string"},"ownerName":{"type":"string"},"logo":{"type":"string","format":"uri"}}}}}}}]},"FindingBase":{"description":"Fields shared across every finding kind.","type":"object","required":["kind","text","comment","feedbackLocation","status","details"],"properties":{"kind":{"type":"string","enum":["policy_feedback","claim","trademark_instance"],"description":"Category of finding returned by Protege."},"text":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Text snippet or extracted value associated with the finding, when available."},"comment":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Reviewer-facing explanation of the issue or recommendation."},"riskLevel":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Severity or risk classification assigned by the review."},"feedbackLocation":{"type":"string","description":"Machine-readable indicator of the content medium where the finding was detected (e.g. 'text', 'image_ocr_text')."},"location":{"$ref":"#/components/schemas/FindingLocation"},"status":{"type":"string","description":"Resolution or approval status associated with the finding."},"approval":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Approval guidance for trademark-related findings, when applicable."},"metadata":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"Additional model-specific or workflow-specific metadata."},"formattedOutput":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Richly formatted version of the finding when available."}}},"FindingLocation":{"description":"Location metadata for a finding within a document.","type":"object","required":["pageNumber"],"properties":{"pageNumber":{"type":"integer"}}},"PolicyRef":{"description":"Lightweight policy reference attached to a finding.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"TrademarkRef":{"description":"Lightweight trademark reference attached to a finding.","type":"object","required":["id","name","proprietary"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"proprietary":{"type":"boolean"},"approval":{"oneOf":[{"type":"string"},{"type":"null"}]},"markType":{"oneOf":[{"type":"string"},{"type":"null"}]}}}}}} ``` ## The RateLimitError object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}}} ``` ## The ReviewDocumentSummary object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ReviewDocumentSummary":{"description":"Summary metadata about the reviewed source document.","type":"object","required":["title","fileType"],"properties":{"title":{"type":"string","description":"Title associated with the reviewed document."},"fileType":{"type":"string","enum":["TEXT","PDF","WEBPAGE","IMAGE","WEBSITE"],"description":"Protege document type classification for the reviewed content."},"externalId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Client-provided identifier echoed back in review responses."}}}}}} ``` ## The CompletedReviewResponse object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"CompletedReviewResponse":{"description":"Final response returned when a document review has completed successfully.","type":"object","required":["id","status","mode","documentId","documentEvaluationTypeId","document","findings"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["completed"]},"mode":{"$ref":"#/components/schemas/ReviewMode"},"documentId":{"type":"string","format":"uuid"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"document":{"$ref":"#/components/schemas/ReviewDocumentSummary"},"findings":{"type":"array","description":"Structured findings produced by the completed review.","items":{"$ref":"#/components/schemas/Finding"}}}},"ReviewMode":{"description":"Controls whether the review should complete inline or be queued for background processing.","type":"string","enum":["sync","async"],"default":"sync"},"ReviewDocumentSummary":{"description":"Summary metadata about the reviewed source document.","type":"object","required":["title","fileType"],"properties":{"title":{"type":"string","description":"Title associated with the reviewed document."},"fileType":{"type":"string","enum":["TEXT","PDF","WEBPAGE","IMAGE","WEBSITE"],"description":"Protege document type classification for the reviewed content."},"externalId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Client-provided identifier echoed back in review responses."}}},"Finding":{"description":"Structured review output describing a policy, trademark, or claim-related issue found in the document. The populated fields depend on the `kind` value.\n","oneOf":[{"$ref":"#/components/schemas/PolicyFeedbackFinding"},{"$ref":"#/components/schemas/ClaimFinding"},{"$ref":"#/components/schemas/TrademarkInstanceFinding"}],"discriminator":{"propertyName":"kind","mapping":{"policy_feedback":"#/components/schemas/PolicyFeedbackFinding","claim":"#/components/schemas/ClaimFinding","trademark_instance":"#/components/schemas/TrademarkInstanceFinding"}}},"PolicyFeedbackFinding":{"description":"A finding produced by a policy evaluation, such as a brand compliance violation.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["policy","details"],"properties":{"policy":{"$ref":"#/components/schemas/PolicyRef"},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Policy-specific detail payload.","properties":{"policyOutputId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the policy output that produced this finding."},"recommendation":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Actionable recommendation for resolving the finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"FindingBase":{"description":"Fields shared across every finding kind.","type":"object","required":["kind","text","comment","feedbackLocation","status","details"],"properties":{"kind":{"type":"string","enum":["policy_feedback","claim","trademark_instance"],"description":"Category of finding returned by Protege."},"text":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Text snippet or extracted value associated with the finding, when available."},"comment":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Reviewer-facing explanation of the issue or recommendation."},"riskLevel":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Severity or risk classification assigned by the review."},"feedbackLocation":{"type":"string","description":"Machine-readable indicator of the content medium where the finding was detected (e.g. 'text', 'image_ocr_text')."},"location":{"$ref":"#/components/schemas/FindingLocation"},"status":{"type":"string","description":"Resolution or approval status associated with the finding."},"approval":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Approval guidance for trademark-related findings, when applicable."},"metadata":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"Additional model-specific or workflow-specific metadata."},"formattedOutput":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Richly formatted version of the finding when available."}}},"FindingLocation":{"description":"Location metadata for a finding within a document.","type":"object","required":["pageNumber"],"properties":{"pageNumber":{"type":"integer"}}},"PolicyRef":{"description":"Lightweight policy reference attached to a finding.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"TrademarkRef":{"description":"Lightweight trademark reference attached to a finding.","type":"object","required":["id","name","proprietary"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"proprietary":{"type":"boolean"},"approval":{"oneOf":[{"type":"string"},{"type":"null"}]},"markType":{"oneOf":[{"type":"string"},{"type":"null"}]}}},"ClaimFinding":{"description":"A finding representing an extracted claim, such as a marketing guarantee or warranty statement.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Claim-specific detail payload.","properties":{"claim":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Canonical claim text extracted from the document."},"disclosureText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Recommended disclosure or qualifying text for a claim finding."},"userFixedText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"User-provided replacement text for a claim finding."},"approvalLimitations":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Scope or limitations tied to an approved claim finding."},"approvalExpireAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Expiration timestamp for an approved claim finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"TrademarkInstanceFinding":{"description":"A finding representing a potential trademark usage issue detected in the document.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["trademark","details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"$ref":"#/components/schemas/TrademarkRef"},"details":{"type":"object","description":"Trademark-specific detail payload.","properties":{"suggestedFixCasing":{"type":"boolean","description":"Whether the trademark instance suggests a casing fix."},"recommendedMarkType":{"type":"string","description":"Recommended mark type for a trademark instance (e.g. 'trademark', 'registered')."},"suggestedMarkExplanation":{"type":"string","description":"Explanation for the recommended mark type."},"suggestedMarkRecord":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"USPTO record details when a trademark match is found.","properties":{"keyword":{"type":"string"},"registrationNumber":{"type":"string"},"registrationDate":{"type":"string"},"statusLabel":{"type":"string"},"ownerName":{"type":"string"},"logo":{"type":"string","format":"uri"}}}}}}}]}}}} ``` ## The PendingReviewResponse object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"PendingReviewResponse":{"description":"Review response returned while an asynchronous review is still queued, processing, or has failed.","type":"object","required":["id","status","mode","documentId","documentEvaluationTypeId","document","findings"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","processing","failed"]},"mode":{"type":"string","enum":["async"]},"documentId":{"type":"string","format":"uuid"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"document":{"$ref":"#/components/schemas/ReviewDocumentSummary"},"findings":{"type":"array","description":"Findings accumulated so far. This is typically empty until processing finishes.","items":{"$ref":"#/components/schemas/Finding"}},"error":{"type":"string","description":"Failure message when the asynchronous review ends in a `failed` state."}}},"ReviewDocumentSummary":{"description":"Summary metadata about the reviewed source document.","type":"object","required":["title","fileType"],"properties":{"title":{"type":"string","description":"Title associated with the reviewed document."},"fileType":{"type":"string","enum":["TEXT","PDF","WEBPAGE","IMAGE","WEBSITE"],"description":"Protege document type classification for the reviewed content."},"externalId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Client-provided identifier echoed back in review responses."}}},"Finding":{"description":"Structured review output describing a policy, trademark, or claim-related issue found in the document. The populated fields depend on the `kind` value.\n","oneOf":[{"$ref":"#/components/schemas/PolicyFeedbackFinding"},{"$ref":"#/components/schemas/ClaimFinding"},{"$ref":"#/components/schemas/TrademarkInstanceFinding"}],"discriminator":{"propertyName":"kind","mapping":{"policy_feedback":"#/components/schemas/PolicyFeedbackFinding","claim":"#/components/schemas/ClaimFinding","trademark_instance":"#/components/schemas/TrademarkInstanceFinding"}}},"PolicyFeedbackFinding":{"description":"A finding produced by a policy evaluation, such as a brand compliance violation.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["policy","details"],"properties":{"policy":{"$ref":"#/components/schemas/PolicyRef"},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Policy-specific detail payload.","properties":{"policyOutputId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the policy output that produced this finding."},"recommendation":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Actionable recommendation for resolving the finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"FindingBase":{"description":"Fields shared across every finding kind.","type":"object","required":["kind","text","comment","feedbackLocation","status","details"],"properties":{"kind":{"type":"string","enum":["policy_feedback","claim","trademark_instance"],"description":"Category of finding returned by Protege."},"text":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Text snippet or extracted value associated with the finding, when available."},"comment":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Reviewer-facing explanation of the issue or recommendation."},"riskLevel":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Severity or risk classification assigned by the review."},"feedbackLocation":{"type":"string","description":"Machine-readable indicator of the content medium where the finding was detected (e.g. 'text', 'image_ocr_text')."},"location":{"$ref":"#/components/schemas/FindingLocation"},"status":{"type":"string","description":"Resolution or approval status associated with the finding."},"approval":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Approval guidance for trademark-related findings, when applicable."},"metadata":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"Additional model-specific or workflow-specific metadata."},"formattedOutput":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Richly formatted version of the finding when available."}}},"FindingLocation":{"description":"Location metadata for a finding within a document.","type":"object","required":["pageNumber"],"properties":{"pageNumber":{"type":"integer"}}},"PolicyRef":{"description":"Lightweight policy reference attached to a finding.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"TrademarkRef":{"description":"Lightweight trademark reference attached to a finding.","type":"object","required":["id","name","proprietary"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"proprietary":{"type":"boolean"},"approval":{"oneOf":[{"type":"string"},{"type":"null"}]},"markType":{"oneOf":[{"type":"string"},{"type":"null"}]}}},"ClaimFinding":{"description":"A finding representing an extracted claim, such as a marketing guarantee or warranty statement.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Claim-specific detail payload.","properties":{"claim":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Canonical claim text extracted from the document."},"disclosureText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Recommended disclosure or qualifying text for a claim finding."},"userFixedText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"User-provided replacement text for a claim finding."},"approvalLimitations":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Scope or limitations tied to an approved claim finding."},"approvalExpireAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Expiration timestamp for an approved claim finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"TrademarkInstanceFinding":{"description":"A finding representing a potential trademark usage issue detected in the document.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["trademark","details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"$ref":"#/components/schemas/TrademarkRef"},"details":{"type":"object","description":"Trademark-specific detail payload.","properties":{"suggestedFixCasing":{"type":"boolean","description":"Whether the trademark instance suggests a casing fix."},"recommendedMarkType":{"type":"string","description":"Recommended mark type for a trademark instance (e.g. 'trademark', 'registered')."},"suggestedMarkExplanation":{"type":"string","description":"Explanation for the recommended mark type."},"suggestedMarkRecord":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"USPTO record details when a trademark match is found.","properties":{"keyword":{"type":"string"},"registrationNumber":{"type":"string"},"registrationDate":{"type":"string"},"statusLabel":{"type":"string"},"ownerName":{"type":"string"},"logo":{"type":"string","format":"uri"}}}}}}}]}}}} ``` ## The DocumentReviewSummary object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"DocumentReviewSummary":{"description":"Summary representation of a review returned by the list endpoint.","type":"object","required":["id","status","documentId","documentEvaluationTypeId","document","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/ReviewStatus"},"documentId":{"type":"string","format":"uuid"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"document":{"$ref":"#/components/schemas/ReviewDocumentSummary"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"error":{"type":"string","description":"Failure message for reviews that completed with an error."}}},"ReviewStatus":{"description":"Current processing state of a submitted document review.","type":"string","enum":["queued","processing","completed","failed"]},"ReviewDocumentSummary":{"description":"Summary metadata about the reviewed source document.","type":"object","required":["title","fileType"],"properties":{"title":{"type":"string","description":"Title associated with the reviewed document."},"fileType":{"type":"string","enum":["TEXT","PDF","WEBPAGE","IMAGE","WEBSITE"],"description":"Protege document type classification for the reviewed content."},"externalId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Client-provided identifier echoed back in review responses."}}}}}} ``` ## The DocumentReviewListResponse object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"DocumentReviewListResponse":{"description":"Paginated collection of reviews visible to the calling API key.","type":"object","required":["documentReviews","page"],"properties":{"documentReviews":{"type":"array","items":{"$ref":"#/components/schemas/DocumentReviewSummary"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"DocumentReviewSummary":{"description":"Summary representation of a review returned by the list endpoint.","type":"object","required":["id","status","documentId","documentEvaluationTypeId","document","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/ReviewStatus"},"documentId":{"type":"string","format":"uuid"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"document":{"$ref":"#/components/schemas/ReviewDocumentSummary"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"error":{"type":"string","description":"Failure message for reviews that completed with an error."}}},"ReviewStatus":{"description":"Current processing state of a submitted document review.","type":"string","enum":["queued","processing","completed","failed"]},"ReviewDocumentSummary":{"description":"Summary metadata about the reviewed source document.","type":"object","required":["title","fileType"],"properties":{"title":{"type":"string","description":"Title associated with the reviewed document."},"fileType":{"type":"string","enum":["TEXT","PDF","WEBPAGE","IMAGE","WEBSITE"],"description":"Protege document type classification for the reviewed content."},"externalId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Client-provided identifier echoed back in review responses."}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}}}}} ``` ## The DocumentEvaluationType object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"DocumentEvaluationType":{"description":"Review configuration that determines which checks, policies, and workflows are applied to a document.","type":"object","required":["id","name","description","useCase"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"}}}}}} ``` ## The DocumentEvaluationTypeListResponse object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"DocumentEvaluationTypeListResponse":{"description":"Paginated list of document evaluation types available to the API key's tenant.","type":"object","required":["documentEvaluationTypes","page"],"properties":{"documentEvaluationTypes":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/DocumentEvaluationType"},{"$ref":"#/components/schemas/ExpandedDocumentEvaluationType"}]}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"DocumentEvaluationType":{"description":"Review configuration that determines which checks, policies, and workflows are applied to a document.","type":"object","required":["id","name","description","useCase"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"}}},"ExpandedDocumentEvaluationType":{"description":"Expanded document evaluation type including its policy groups and nested policies.","allOf":[{"$ref":"#/components/schemas/DocumentEvaluationType"},{"type":"object","required":["policyGroups"],"properties":{"policyGroups":{"type":"array","items":{"$ref":"#/components/schemas/ExpandedPolicyGroup"}}}}]},"ExpandedPolicyGroup":{"allOf":[{"$ref":"#/components/schemas/PolicyGroup"},{"type":"object","required":["policies"],"properties":{"policies":{"type":"array","items":{"$ref":"#/components/schemas/NestedPolicy"}}}}]},"PolicyGroup":{"description":"Grouping of related review policies used to organize evaluation coverage.","type":"object","required":["id","name","description","useCase"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"prePolicy":{"oneOf":[{"$ref":"#/components/schemas/PolicyPrePolicyRef"},{"type":"null"}]}}},"PolicyPrePolicyRef":{"description":"Reference to a prerequisite or pre-check policy associated with a policy group.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"NestedPolicy":{"description":"Policy summary embedded under parent resources such as policy groups.","type":"object","required":["id","name","description","useCase","enabled","riskLevel"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"enabled":{"type":"boolean","description":"Whether the policy is currently active and evaluated."},"riskLevel":{"type":"string","description":"Severity or risk classification assigned to this policy."}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}}}}} ``` ## The PolicyGroupRef object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"PolicyGroupRef":{"description":"Lightweight reference to a policy group.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}} ``` ## The PolicyPrePolicyRef object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"PolicyPrePolicyRef":{"description":"Reference to a prerequisite or pre-check policy associated with a policy group.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}} ``` ## The NestedPolicy object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"NestedPolicy":{"description":"Policy summary embedded under parent resources such as policy groups.","type":"object","required":["id","name","description","useCase","enabled","riskLevel"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"enabled":{"type":"boolean","description":"Whether the policy is currently active and evaluated."},"riskLevel":{"type":"string","description":"Severity or risk classification assigned to this policy."}}}}}} ``` ## The Policy object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"Policy":{"description":"Full policy record returned by the policies endpoint.","allOf":[{"$ref":"#/components/schemas/NestedPolicy"},{"type":"object","properties":{"policyGroup":{"oneOf":[{"$ref":"#/components/schemas/PolicyGroupRef"},{"type":"null"}]}}}]},"NestedPolicy":{"description":"Policy summary embedded under parent resources such as policy groups.","type":"object","required":["id","name","description","useCase","enabled","riskLevel"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"enabled":{"type":"boolean","description":"Whether the policy is currently active and evaluated."},"riskLevel":{"type":"string","description":"Severity or risk classification assigned to this policy."}}},"PolicyGroupRef":{"description":"Lightweight reference to a policy group.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}} ``` ## The PolicyListResponse object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"PolicyListResponse":{"description":"Paginated collection of policies.","type":"object","required":["policies","page"],"properties":{"policies":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"Policy":{"description":"Full policy record returned by the policies endpoint.","allOf":[{"$ref":"#/components/schemas/NestedPolicy"},{"type":"object","properties":{"policyGroup":{"oneOf":[{"$ref":"#/components/schemas/PolicyGroupRef"},{"type":"null"}]}}}]},"NestedPolicy":{"description":"Policy summary embedded under parent resources such as policy groups.","type":"object","required":["id","name","description","useCase","enabled","riskLevel"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"enabled":{"type":"boolean","description":"Whether the policy is currently active and evaluated."},"riskLevel":{"type":"string","description":"Severity or risk classification assigned to this policy."}}},"PolicyGroupRef":{"description":"Lightweight reference to a policy group.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}}}}} ``` ## The PolicyGroup object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"PolicyGroup":{"description":"Grouping of related review policies used to organize evaluation coverage.","type":"object","required":["id","name","description","useCase"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"prePolicy":{"oneOf":[{"$ref":"#/components/schemas/PolicyPrePolicyRef"},{"type":"null"}]}}},"PolicyPrePolicyRef":{"description":"Reference to a prerequisite or pre-check policy associated with a policy group.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}} ``` ## The ExpandedPolicyGroup object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ExpandedPolicyGroup":{"allOf":[{"$ref":"#/components/schemas/PolicyGroup"},{"type":"object","required":["policies"],"properties":{"policies":{"type":"array","items":{"$ref":"#/components/schemas/NestedPolicy"}}}}]},"PolicyGroup":{"description":"Grouping of related review policies used to organize evaluation coverage.","type":"object","required":["id","name","description","useCase"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"prePolicy":{"oneOf":[{"$ref":"#/components/schemas/PolicyPrePolicyRef"},{"type":"null"}]}}},"PolicyPrePolicyRef":{"description":"Reference to a prerequisite or pre-check policy associated with a policy group.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"NestedPolicy":{"description":"Policy summary embedded under parent resources such as policy groups.","type":"object","required":["id","name","description","useCase","enabled","riskLevel"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"enabled":{"type":"boolean","description":"Whether the policy is currently active and evaluated."},"riskLevel":{"type":"string","description":"Severity or risk classification assigned to this policy."}}}}}} ``` ## The PolicyGroupListResponse object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"PolicyGroupListResponse":{"description":"Paginated collection of policy groups.","type":"object","required":["policyGroups","page"],"properties":{"policyGroups":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/PolicyGroup"},{"$ref":"#/components/schemas/ExpandedPolicyGroup"}]}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"PolicyGroup":{"description":"Grouping of related review policies used to organize evaluation coverage.","type":"object","required":["id","name","description","useCase"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"prePolicy":{"oneOf":[{"$ref":"#/components/schemas/PolicyPrePolicyRef"},{"type":"null"}]}}},"PolicyPrePolicyRef":{"description":"Reference to a prerequisite or pre-check policy associated with a policy group.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ExpandedPolicyGroup":{"allOf":[{"$ref":"#/components/schemas/PolicyGroup"},{"type":"object","required":["policies"],"properties":{"policies":{"type":"array","items":{"$ref":"#/components/schemas/NestedPolicy"}}}}]},"NestedPolicy":{"description":"Policy summary embedded under parent resources such as policy groups.","type":"object","required":["id","name","description","useCase","enabled","riskLevel"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"enabled":{"type":"boolean","description":"Whether the policy is currently active and evaluated."},"riskLevel":{"type":"string","description":"Severity or risk classification assigned to this policy."}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}}}}} ``` ## The ExpandedDocumentEvaluationType object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ExpandedDocumentEvaluationType":{"description":"Expanded document evaluation type including its policy groups and nested policies.","allOf":[{"$ref":"#/components/schemas/DocumentEvaluationType"},{"type":"object","required":["policyGroups"],"properties":{"policyGroups":{"type":"array","items":{"$ref":"#/components/schemas/ExpandedPolicyGroup"}}}}]},"DocumentEvaluationType":{"description":"Review configuration that determines which checks, policies, and workflows are applied to a document.","type":"object","required":["id","name","description","useCase"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"}}},"ExpandedPolicyGroup":{"allOf":[{"$ref":"#/components/schemas/PolicyGroup"},{"type":"object","required":["policies"],"properties":{"policies":{"type":"array","items":{"$ref":"#/components/schemas/NestedPolicy"}}}}]},"PolicyGroup":{"description":"Grouping of related review policies used to organize evaluation coverage.","type":"object","required":["id","name","description","useCase"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"prePolicy":{"oneOf":[{"$ref":"#/components/schemas/PolicyPrePolicyRef"},{"type":"null"}]}}},"PolicyPrePolicyRef":{"description":"Reference to a prerequisite or pre-check policy associated with a policy group.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"NestedPolicy":{"description":"Policy summary embedded under parent resources such as policy groups.","type":"object","required":["id","name","description","useCase","enabled","riskLevel"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"useCase":{"type":"string","enum":["marketing_review","document_qa"],"description":"Determines what the evaluation type is optimized for. `marketing_review` analyzes documents and web content for compliance against brand policies. `document_qa` extracts structured content from documents and websites for specific queries and document-level grouping.\n"},"enabled":{"type":"boolean","description":"Whether the policy is currently active and evaluated."},"riskLevel":{"type":"string","description":"Severity or risk classification assigned to this policy."}}}}}} ``` ## The Brand object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"Brand":{"description":"Brand available to the authenticated tenant for filtering scanners and reports.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}} ``` ## The BrandListResponse object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"BrandListResponse":{"description":"Paginated collection of brands.","type":"object","required":["brands","page"],"properties":{"brands":{"type":"array","items":{"$ref":"#/components/schemas/Brand"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"Brand":{"description":"Brand available to the authenticated tenant for filtering scanners and reports.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}}}}} ``` ## The PageMetadata object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}}}}} ``` ## The ReportBrand object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ReportBrand":{"description":"Lightweight brand reference attached to a scanner report.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}} ``` ## The ReportListItem object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ReportListItem":{"description":"Summary representation of a scanner report.","type":"object","required":["id","name","createdAt","documentCount"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"brand":{"oneOf":[{"$ref":"#/components/schemas/ReportBrand"},{"type":"null"}]},"documentCount":{"type":"integer"}}},"ReportBrand":{"description":"Lightweight brand reference attached to a scanner report.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}} ``` ## The ReportDetailSummary object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ReportDetailSummary":{"description":"Top-level report metadata returned with detailed report responses.","type":"object","required":["id","name","createdAt","documentCount"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"brand":{"oneOf":[{"$ref":"#/components/schemas/ReportBrand"},{"type":"null"}]},"documentCount":{"type":"integer"}}},"ReportBrand":{"description":"Lightweight brand reference attached to a scanner report.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}} ``` ## The ReportPage object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ReportPage":{"description":"Page or document captured within a scanner report.","type":"object","required":["documentId","title","fileType","createdAt"],"properties":{"documentId":{"type":"string","format":"uuid"},"title":{"type":"string"},"link":{"oneOf":[{"type":"string"},{"type":"null"}]},"fileType":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"lastScannedAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}}}}} ``` ## The ReportListResponse object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ReportListResponse":{"description":"Paginated collection of scanner reports.","type":"object","required":["reports","page"],"properties":{"reports":{"type":"array","items":{"$ref":"#/components/schemas/ReportListItem"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"ReportListItem":{"description":"Summary representation of a scanner report.","type":"object","required":["id","name","createdAt","documentCount"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"brand":{"oneOf":[{"$ref":"#/components/schemas/ReportBrand"},{"type":"null"}]},"documentCount":{"type":"integer"}}},"ReportBrand":{"description":"Lightweight brand reference attached to a scanner report.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}}}}} ``` ## The ReportDetail object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ReportDetail":{"description":"Report detail including captured pages and page-level metadata.","allOf":[{"$ref":"#/components/schemas/ReportDetailSummary"},{"type":"object","required":["pages"],"properties":{"pages":{"type":"array","items":{"$ref":"#/components/schemas/ReportPage"}}}}]},"ReportDetailSummary":{"description":"Top-level report metadata returned with detailed report responses.","type":"object","required":["id","name","createdAt","documentCount"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"brand":{"oneOf":[{"$ref":"#/components/schemas/ReportBrand"},{"type":"null"}]},"documentCount":{"type":"integer"}}},"ReportBrand":{"description":"Lightweight brand reference attached to a scanner report.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ReportPage":{"description":"Page or document captured within a scanner report.","type":"object","required":["documentId","title","fileType","createdAt"],"properties":{"documentId":{"type":"string","format":"uuid"},"title":{"type":"string"},"link":{"oneOf":[{"type":"string"},{"type":"null"}]},"fileType":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"lastScannedAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}}}}} ``` ## The ScannerJobBrand object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ScannerJobBrand":{"description":"Brand assigned to a scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}} ``` ## The ScannerJobDocumentEvaluationType object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ScannerJobDocumentEvaluationType":{"description":"Review configuration applied to content discovered by the scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}} ``` ## The ScannerJobRunSummary object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ScannerJobRunSummary":{"description":"High-level status for a single execution of a scanner job.","type":"object","required":["id","status","scheduledTime","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CREATED","RUNNING","FINISHED","FAILED"]},"scheduledTime":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}}}}} ``` ## The ScannerJobRun object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ScannerJobRun":{"description":"Detailed execution metadata for a scanner job run.","allOf":[{"$ref":"#/components/schemas/ScannerJobRunSummary"},{"type":"object","required":["updatedAt"],"properties":{"updatedAt":{"type":"string","format":"date-time"}}}]},"ScannerJobRunSummary":{"description":"High-level status for a single execution of a scanner job.","type":"object","required":["id","status","scheduledTime","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CREATED","RUNNING","FINISHED","FAILED"]},"scheduledTime":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}}}}} ``` ## The ScannerJob object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ScannerJob":{"description":"Scanner job summary returned by list and create operations.","type":"object","required":["id","urls"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"oneOf":[{"type":"string"},{"type":"null"}]},"urls":{"type":"array","items":{"type":"string","format":"uri"}},"scheduler":{"oneOf":[{"type":"string"},{"type":"null"}]},"brand":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobBrand"},{"type":"null"}]},"documentEvaluationType":{"$ref":"#/components/schemas/ScannerJobDocumentEvaluationType"},"lastRun":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobRunSummary"},{"type":"null"}]}}},"ScannerJobBrand":{"description":"Brand assigned to a scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobDocumentEvaluationType":{"description":"Review configuration applied to content discovered by the scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobRunSummary":{"description":"High-level status for a single execution of a scanner job.","type":"object","required":["id","status","scheduledTime","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CREATED","RUNNING","FINISHED","FAILED"]},"scheduledTime":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}}}}} ``` ## The ScannerJobDetail object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ScannerJobDetail":{"description":"Full scanner job configuration, including crawl and archival options.","allOf":[{"$ref":"#/components/schemas/ScannerJob"},{"type":"object","required":["showAllFeedbackInDecisionStore","translationEnabled"],"properties":{"maxPages":{"oneOf":[{"type":"integer"},{"type":"null"}]},"maxDepth":{"oneOf":[{"type":"integer"},{"type":"null"}]},"maxTrackedPages":{"oneOf":[{"type":"integer"},{"type":"null"}]},"newPagesForSuccessiveScans":{"oneOf":[{"type":"integer"},{"type":"null"}]},"showAllFeedbackInDecisionStore":{"type":"boolean"},"translationEnabled":{"type":"boolean"},"useSitemaps":{"oneOf":[{"type":"boolean"},{"type":"null"}]},"archiveMode":{"oneOf":[{"type":"string","enum":["ON_FOR_ALL","ON_FOR_BRAND_MENTIONED"]},{"type":"null"}]}}}]},"ScannerJob":{"description":"Scanner job summary returned by list and create operations.","type":"object","required":["id","urls"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"oneOf":[{"type":"string"},{"type":"null"}]},"urls":{"type":"array","items":{"type":"string","format":"uri"}},"scheduler":{"oneOf":[{"type":"string"},{"type":"null"}]},"brand":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobBrand"},{"type":"null"}]},"documentEvaluationType":{"$ref":"#/components/schemas/ScannerJobDocumentEvaluationType"},"lastRun":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobRunSummary"},{"type":"null"}]}}},"ScannerJobBrand":{"description":"Brand assigned to a scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobDocumentEvaluationType":{"description":"Review configuration applied to content discovered by the scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobRunSummary":{"description":"High-level status for a single execution of a scanner job.","type":"object","required":["id","status","scheduledTime","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CREATED","RUNNING","FINISHED","FAILED"]},"scheduledTime":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}}}}} ``` ## The ScannerJobListResponse object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ScannerJobListResponse":{"description":"Paginated collection of scanner jobs.","type":"object","required":["scannerJobs","page"],"properties":{"scannerJobs":{"type":"array","items":{"$ref":"#/components/schemas/ScannerJob"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"ScannerJob":{"description":"Scanner job summary returned by list and create operations.","type":"object","required":["id","urls"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"oneOf":[{"type":"string"},{"type":"null"}]},"urls":{"type":"array","items":{"type":"string","format":"uri"}},"scheduler":{"oneOf":[{"type":"string"},{"type":"null"}]},"brand":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobBrand"},{"type":"null"}]},"documentEvaluationType":{"$ref":"#/components/schemas/ScannerJobDocumentEvaluationType"},"lastRun":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobRunSummary"},{"type":"null"}]}}},"ScannerJobBrand":{"description":"Brand assigned to a scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobDocumentEvaluationType":{"description":"Review configuration applied to content discovered by the scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobRunSummary":{"description":"High-level status for a single execution of a scanner job.","type":"object","required":["id","status","scheduledTime","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CREATED","RUNNING","FINISHED","FAILED"]},"scheduledTime":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}}}}} ``` ## The ScannerJobDetailResponse object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ScannerJobDetailResponse":{"description":"Wrapper containing a single scanner job record.","type":"object","required":["scannerJob"],"properties":{"scannerJob":{"$ref":"#/components/schemas/ScannerJobDetail"}}},"ScannerJobDetail":{"description":"Full scanner job configuration, including crawl and archival options.","allOf":[{"$ref":"#/components/schemas/ScannerJob"},{"type":"object","required":["showAllFeedbackInDecisionStore","translationEnabled"],"properties":{"maxPages":{"oneOf":[{"type":"integer"},{"type":"null"}]},"maxDepth":{"oneOf":[{"type":"integer"},{"type":"null"}]},"maxTrackedPages":{"oneOf":[{"type":"integer"},{"type":"null"}]},"newPagesForSuccessiveScans":{"oneOf":[{"type":"integer"},{"type":"null"}]},"showAllFeedbackInDecisionStore":{"type":"boolean"},"translationEnabled":{"type":"boolean"},"useSitemaps":{"oneOf":[{"type":"boolean"},{"type":"null"}]},"archiveMode":{"oneOf":[{"type":"string","enum":["ON_FOR_ALL","ON_FOR_BRAND_MENTIONED"]},{"type":"null"}]}}}]},"ScannerJob":{"description":"Scanner job summary returned by list and create operations.","type":"object","required":["id","urls"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"oneOf":[{"type":"string"},{"type":"null"}]},"urls":{"type":"array","items":{"type":"string","format":"uri"}},"scheduler":{"oneOf":[{"type":"string"},{"type":"null"}]},"brand":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobBrand"},{"type":"null"}]},"documentEvaluationType":{"$ref":"#/components/schemas/ScannerJobDocumentEvaluationType"},"lastRun":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobRunSummary"},{"type":"null"}]}}},"ScannerJobBrand":{"description":"Brand assigned to a scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobDocumentEvaluationType":{"description":"Review configuration applied to content discovered by the scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobRunSummary":{"description":"High-level status for a single execution of a scanner job.","type":"object","required":["id","status","scheduledTime","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CREATED","RUNNING","FINISHED","FAILED"]},"scheduledTime":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}}}}} ``` ## The ScannerJobRunsResponse object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ScannerJobRunsResponse":{"description":"Paginated collection of historical runs for a scanner job.","type":"object","required":["scannerRuns","page"],"properties":{"scannerRuns":{"type":"array","items":{"$ref":"#/components/schemas/ScannerJobRun"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"ScannerJobRun":{"description":"Detailed execution metadata for a scanner job run.","allOf":[{"$ref":"#/components/schemas/ScannerJobRunSummary"},{"type":"object","required":["updatedAt"],"properties":{"updatedAt":{"type":"string","format":"date-time"}}}]},"ScannerJobRunSummary":{"description":"High-level status for a single execution of a scanner job.","type":"object","required":["id","status","scheduledTime","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CREATED","RUNNING","FINISHED","FAILED"]},"scheduledTime":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}}}}} ``` ## The ScannerJobUpdateRequest object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ScannerJobUpdateRequest":{"description":"Partial update payload for a scanner job. Include only the fields you want to change.","type":"object","minProperties":1,"properties":{"name":{"type":"string"},"urls":{"type":"array","minItems":1,"items":{"type":"string","format":"uri"}},"scheduler":{"oneOf":[{"type":"string"},{"type":"null"}]},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"brandId":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"maxPages":{"type":"integer"},"maxDepth":{"type":"integer"},"maxTrackedPages":{"type":"integer","minimum":1},"newPagesForSuccessiveScans":{"type":"integer","minimum":0},"showAllFeedbackInDecisionStore":{"type":"boolean"},"translationEnabled":{"type":"boolean"},"useSitemaps":{"type":"boolean"},"archiveMode":{"oneOf":[{"type":"string","enum":["ON_FOR_ALL","ON_FOR_BRAND_MENTIONED"]},{"type":"null"}]}}}}}} ``` ## The ScannerJobCreateRequest object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ScannerJobCreateRequest":{"description":"Request body used to create a new scanner job.","type":"object","required":["name","documentEvaluationTypeId","urls"],"properties":{"name":{"type":"string"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"urls":{"type":"array","items":{"type":"string","format":"uri"}},"scheduler":{"type":"string"},"maxPages":{"type":"integer"},"maxDepth":{"type":"integer"},"maxTrackedPages":{"type":"integer","minimum":1},"newPagesForSuccessiveScans":{"type":"integer","minimum":0},"brandId":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"showAllFeedbackInDecisionStore":{"type":"boolean"},"translationEnabled":{"type":"boolean"},"useSitemaps":{"type":"boolean"},"archiveMode":{"oneOf":[{"type":"string","enum":["ON_FOR_ALL","ON_FOR_BRAND_MENTIONED"]},{"type":"null"}]}}}}}} ``` ## The ScannerJobCreateResponse object ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"components":{"schemas":{"ScannerJobCreateResponse":{"description":"Wrapper returned after a scanner job is created successfully.","type":"object","required":["scannerJob"],"properties":{"scannerJob":{"$ref":"#/components/schemas/ScannerJob"}}},"ScannerJob":{"description":"Scanner job summary returned by list and create operations.","type":"object","required":["id","urls"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"oneOf":[{"type":"string"},{"type":"null"}]},"urls":{"type":"array","items":{"type":"string","format":"uri"}},"scheduler":{"oneOf":[{"type":"string"},{"type":"null"}]},"brand":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobBrand"},{"type":"null"}]},"documentEvaluationType":{"$ref":"#/components/schemas/ScannerJobDocumentEvaluationType"},"lastRun":{"oneOf":[{"$ref":"#/components/schemas/ScannerJobRunSummary"},{"type":"null"}]}}},"ScannerJobBrand":{"description":"Brand assigned to a scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobDocumentEvaluationType":{"description":"Review configuration applied to content discovered by the scanner job.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ScannerJobRunSummary":{"description":"High-level status for a single execution of a scanner job.","type":"object","required":["id","status","scheduledTime","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CREATED","RUNNING","FINISHED","FAILED"]},"scheduledTime":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}}}}} ``` # Document Review Document Reviews in Protege Counsel allow users to specify the parameters for analyzing content based on specific document policy configurations. Each document review type can comprise multiple policy groups, providing comprehensive assessment criteria tailored to different document types or contexts. **Overview:** Document Reviews serve as customizable frameworks for evaluating content, enabling users to define the scope and criteria for analysis according to their requirements. By assigning policy groups to document review types, users can ensure a thorough examination of content for legal risks and compliance considerations.\ \ **Example Document Review Types:** 1. **Marketing Material Review**: * Policy Groups: * Core SaaS Policies * Marketing Compliance Guidelines * Branding and Messaging Standards 2. **Document Request Review**: * Policy Groups: * Sender Identification * Requirements Policy * Case Number Identification 3. **Social Media Review** * Policy Groups: * Claims Policy * Trademark Policy * Sponsorship Disclosure Policy **Managing Document Reviews:** Document reviews can be managed and different Policy Groups attached as needed. To make a change, users should write into support to create Policies, adjust Policy Groups, or create new Document Reviews to accommodate evolving company requirements. The support email is , or you can use your shared external channel with the Protege team. Enterprise customers who want to integrate Protege into their own systems or agent workflows should start with the enterprise integration guide: {% content-ref url="/pages/kPBUSnugF2uhvh9BvOQw" %} [Integrations & API](/review/enterprise-features/integrations-and-api) {% endcontent-ref %} \ If you have any questions or need assistance with setting up or managing document reviews, please don't hesitate to reach out to our support team for guidance. We're here to help you optimize your content review workflows and ensure compliance with ease. # Policy Engine In Protege, policies are essential guidelines used to evaluate content for legal risks during document editing or attachment review. Think of these as heuristics or guidelines the AI is coached to look for. These policies are organized into policy groups, which allow users to apply multiple policies collectively to specific document types for thorough analysis.
**Document Evaluations Structure:** A Document Evaluation is a structured assessment that can be applied to each type of document reviewed within the Protege AI system. This evaluation assesses documents against specific criteria defined by the organization’s policy requirements. **Example**: Basic Review (included in most customer's environment). Included Policy Groups: * Trademark and Claims Policy Group. Included Policies: * Trademark Identification * Claim Identification **Policy Group Structure:** A policy group consists of multiple policies bundled together. Users can assign policy groups to specific document types to streamline the review process. For instance, a policy group may include various policies relevant to a particular category or context. **Example**: Core SaaS Policies. Included Policies: * Claims: Identify claims about the product or service. * Competitive References: Generally avoid references to competitors; focus on the value of the organization’s products, services, or features. * Compliance Guidelines: Ensure compliance with industry regulations and standards. \ **Policy Structure:** * **Name**: Competitive References * **Description**: Generally avoid references to competitors; focus on the value of the organization’s products, services, or features. * **Steps**: 1. Identify the sentences that reference competitors. 2. Provide an explanation for the text, emphasizing the importance of focusing on the organization's offerings rather than competitors. **Example Policy:** * **Policy**: A policy represents a specific guideline or rule used to assess content for legal risks. Each policy consists of the following components: * **Name**: Describes the title of the policy, providing a clear indication of its purpose. * **Description**: Offers a brief explanation of the policy's objective and guidelines for compliance. * **Steps**: Outlines the actions or procedures involved in implementing the policy's guidelines effectively. *** By leveraging policies and policy groups, users can ensure thorough and consistent evaluation of content for legal risks, ultimately enhancing compliance and mitigating potential liabilities. If you have any questions or need further assistance regarding policy management or document review processes, please don't hesitate to reach out to our support team.\
# Viewing **Viewing Policies, Policy Groups, and Evaluation Types** 1. **Access the Dashboard**: Log in to your Protege account via the dashboard at [app.t](https://app.protegecounsel.ai/)[ryprotege.com](https://app.tryprotege.com). 2. **Click on the "Policy Engine" Tab**: Locate and click on the "Policy Engine" tab in the navigation menu. This will take you to the section where all policies and policy groups are managed. 3. **Review Policy Groups**: Once in the Policy Engine section, you'll find a list of Policy Groups displayed. Each Policy Group represents a collection of related policies bundled together for content evaluation. 4. **Explore Policy Details**: Within each Policy Group, you'll see the individual policies it contains. Click on any specific policy to expand it and view detailed steps outlining the procedures and criteria involved in implementing that particular policy. 5. **View Document Evaluations**: Each type of Document that you set for review in Protege AI can be assigned different Policy Groups to be conducted. # Editing & Adding ### **Overview** The Policy Engine feature in Protege AI allows users to create, modify, and refine policies that govern how documents and other media are evaluated. This section outlines the process for adding and editing policies within a specific Policy Group. ### **Adding a New Policy** To introduce a new policy into your system, follow these simple steps: **Steps to Add a New Policy:** 1. **Navigate to the Desired Policy Group**: Access the Policy Group where the new policy will be housed. 2. **Add New Policy**: Click on "Add New Policy" to initiate the creation of a new policy within the selected group.
### **Configuration of a Policy** When setting up a new policy or editing an existing one, it’s crucial to specify the mediums on which the policy should be applied. These settings ensure that the policy is appropriately targeted and effective across different types of content. The mediums currently available for Policy Application are: | Medium | Description | Example Tools/Use Cases | | --------------------- | ------------------------------------------------------------------------------ | --------------------------------------- | | Text | Directs the policy towards analyzing the text content in documents. | Google Doc, Microsoft Word, Figma | | Web Hidden Text | Content scanner for hidden web content. | Content scanner | | Image OCR Text | Applies the policy to the OCR text extracted from submitted image attachments. | Images and websites | | Image Query | Run a prompt with a large vision model to analyze an image. | Images and websites | | Video Unique OCR Text | Analyzes all the deduplicated visible text in a video. | Videos, Instagram videos, TikTok videos | | Video Transcript | Applies the policy to the transcript derived from a video’s audio. | Videos, Instagram videos, TikTok videos | ### **Risk Level** The **Risk Level** setting allows you to classify policy feedback as **High**, **Medium**, or **Low** risk, based on customizable prompts. This enables granular control over how your policies interpret and prioritize different types of content, providing targeted feedback and actions depending on the potential impact or sensitivity of the detected issue. #### Example Use Case: Product Comparisons Suppose you have a policy to identify product comparisons in your documentation or communication, but you want to handle comparisons involving a specific competitor with greater scrutiny. * **High Risk Prompt:**\ `Identify sentences that compare us to [competitor]` * **Fallback Risk Level:**\ Set to **Low**.
#### Best Practices * **Be Specific in Prompts:** The clearer your prompts, the more accurately the system can classify risk. * **Review and Iterate:** Periodically review flagged feedback and adjust prompts to reduce false positives/negatives. * **Use Fallbacks:** Always set a fallback risk level to ensure all content receives a risk classification. ### **Special Policy Type** Ccustomers defined Policies should leave this field blank. While most policies are classified as General Policies and use customizable prompts from Language Learning Models (LLMs), Protege AI also supports special policies with preset logic for specific purposes. ### **Steps** Each Policy, except for the Special Type described above, is composed of a series of steps. Learn more about [Steps](/review/review-tool-concepts/document-review/policy-engine/steps).
*** This section provides detailed guidance on how to effectively manage and edit policies within Protege AI, ensuring that they are well-suited to the media types and specific needs of the organization. By properly configuring these settings, users can optimize the document evaluation process and enhance overall compliance and efficiency. \
# Steps Steps in a Policy Group in Protege AI *** **Note: This page is still in beta and recommended only for power-users. Regular uses are recommended to reach out to their support team to create new or make significant edits to Policies.** **Overview** Policy Groups in Protege AI are designed to streamline the evaluation process through a series of interconnected steps. These steps are linked based on the input and output variables they handle, forming a sequential workflow that ensures thorough document analysis and feedback generation. **Step Linkage** Each step within a Policy Group is interconnected through defined input and output variables: * **Identifiers** have defined output variables. * **Responders** have input variables that correspond to the outputs from the Identifiers. By default, the action types for the preceding and next steps are set to success. In other words, if an identifier step finds a match, it will pass it to the output variable. The responder will read the input variable and proceed based on the value. However, in scenarios where the policy aims to detect missing but expected text, the configuration changes: * **Next Step Action**: Set this to failure if the policy needs to identify absent but expected text. * **Responder Steps**: Should have a preceding step action type of failure to handle these specific cases. **Identifier Steps** These steps are crucial as they determine whether specific language, prompts, or text are present in the document. **Types of Identifier Steps:** 1. **Prompt Identification**: Utilizes an LLM prompt to identify phrasing or intent within the text. The input text should be set to Page for most cases. 2. **Match Text Identification**: Directly scans the text (case insensitive) for specific phrases or words outlined in the policy. **Responder Steps** Following identification, Responder Steps take the outputs from Identifier Steps and create actionable feedback for the user. **Types of Responder Steps:** 1. **Fixed Suggestion**: Provides a predetermined response or suggestion directly to the user. 2. **Prompt Suggestion**: Generates a suggestion based on a prompt and the prior inputs identified in the document. 3. **Doc Explanation**: If an identifier step is triggered, a suggestion is displayed at the top of the document to inform the user of the general issue. 4. **Explanation**: For each occurrence detected by an identifier step, a suggestion is displayed at that specific location within the document.
*** This structured approach in setting up Policy Groups ensures that documents are not only reviewed for compliance and accuracy but also that detailed, context-specific feedback is provided to enhance the user's understanding and compliance with organizational standards. Through effective use of identifiers and responders, Protege AI facilitates a comprehensive document review process that adapts to various content types and policy requirements. # Feedback Cards {% content-ref url="/pages/GstMKCAWDyjJT6SFPQCf" %} [Trademarks](/review/review-tool-concepts/document-review/feedback-cards/trademarks) {% endcontent-ref %} {% content-ref url="/pages/oiQVzM4RBBcRgzRD7qgG" %} [Policy Feedback](/review/review-tool-concepts/document-review/feedback-cards/policy-feedback) {% endcontent-ref %} {% content-ref url="/pages/vjqJow3hM4SOLNs70pBB" %} [Product Claims](/review/review-tool-concepts/document-review/feedback-cards/product-claims) {% endcontent-ref %} {% content-ref url="/pages/noLIs5ySTfALGNxoQ1mZ" %} [Comment Generator](/review/review-tool-concepts/document-review/feedback-cards/comment-generator) {% endcontent-ref %} # Trademarks The Trademark feedback feature enhances the document scanning process by providing valuable insights and guidance related to brand name usage and trademark compliance. This feedback is particularly valuable for legal professionals and organizations seeking to protect their brand identity and intellectual property rights. The Trademark feedback encompasses two types of checks: Trademarks and Trademark Types. **Overview:** * **Trademarks Check:** The Trademarks check assesses whether the usage of a brand name in the document has been cleared and if it has been previously used elsewhere. If the brand name is encountered for the first time, it can be approved within Protege using the ✅ button. * **Standing Approval**: Standing approval grants blanket permission for the usage of a brand name, indicating that it has been thoroughly vetted and is cleared for use without further review. Users can also set an expiration time for standing approvals to ensure ongoing compliance. * **Limited Approval**: For brand names requiring special considerations or limitations, a limited approval can be granted. This allows users to specify restrictions or conditions that are reflected in future references, such as "requires partner legal notification." * **Trademark Types Check:** Protege will also search the United States Patent and Trademark Office (USPTO) to confirm if the trademark is registered. * If the trademark is registered, a reminder to check for brand guidelines is added. * Additionally, the card will show if the TM, SM, or ® is appropriate based on the registration and document context.
You can see a list of all approved trademarks in the Decision Store. Learn more about the[Decision Store](/review/review-tool-concepts/decision-store). By incorporating Trademark feedback into the document scanning process, Protege empowers users to proactively address trademark-related concerns, ensure compliance with intellectual property laws, and safeguard their brand assets effectively. This feature serves as a valuable tool for legal professionals and businesses seeking to maintain brand integrity and mitigate potential legal risks associated with trademark infringement. # Policy Feedback Policy feedback within Protege encompasses a wide range of evaluations beyond trademarks and claims, helping ensure compliance, accuracy, and completeness of content across various document types. This feature is instrumental for compliance, legal, and marketers to quickly identify issues that may become regulatory and legal risks, and identify contractual obligations. When a Policy Feedback appears in a review, you can Acknowledge, Resolve, or Teach your AI to improve the feedback detection. To dive into that more, check the [Customize Feedback Behavior](/review/review-tool-concepts/teach-your-ai/customize-feedback-behavior) section in Teach your AI.\ \ **Policy Feedbacks Categories** **Fix and Replace:** * **Description**: Reserved for the most critical language that poses high-risk implications. For example, absolute guarantees or commitments may be flagged for adjustment. * **Action**: Protege generates several suggestions to make the language more conservative, reducing potential legal liabilities and ensuring compliance with regulations. **Specific Text Warning:** * **Description**: Highlights instances where specific phrasing may be missing or requires clarification to accurately and transparently disclose product, service, or feature limitations. * **Action**: Users are prompted to review and ensure that all necessary disclosures and disclaimers are included to provide clarity to the reader and mitigate misunderstandings. **Document Warning:** * **Description**: Alerts users to ensure that specific requirements or disclosures are met within the document. This could include mandated disclosures or regulatory compliance measures. * **Action**: Users are prompted to quickly verify that all necessary requirements are fulfilled to avoid potential legal repercussions or regulatory penalties. **Highlight:** * **Description**: Provides awareness of specific text that should be flagged for attention. This could include product definitions, terminology, or contract clauses that require careful consideration. * **Action**: Users are alerted to review highlighted text for accuracy, completeness, and alignment with legal standards and contractual obligations.
\ This feature facilitates collaboration between legal and business teams, promoting transparency, accuracy, and accountability in content creation and review processes. # Product Claims Product Claims feedback within Protege Counsel enhances the document scanning process by identifying assertions about products or services, allowing users to evaluate their accuracy and potential legal risks. This feature is invaluable for legal professionals and marketers seeking to ensure compliance with advertising regulations and avoid misleading statements. The Claims feedback includes the following components:
**Claim Identification:** Protege identifies claims made within the document related to products or services. These claims are flagged for review to assess their accuracy and potential legal implications.\ \ **Overview:** * **Intro**: Each identified claim is presented in a feedback card format. At the top of the card, a ✅ indicates that the claim is likely low risk due to past precedent or validation. * **Explanation**: The explanation identifies the likely risks with the claim. * **Suggestions**: These are proposed alternatives that aims to remove the riskiness of the language. Pressing the suggestions replaces it in the Google Doc. * **Similar Claims:** If there are similar statements that have been made in the past, they will be displayed here. High and Medium similarity matches show up by default, and there is an option to view low similarity matches by pressing "Show More". Each claim that appears will also have a usage label: * **In Use.** Claims that are already used publicly or in a document that was approved. * **Standing Approval.** The text was previously explicitly approved for usage. * **Limited Approval.** The text was given condition approval, highlight over for specifics. * **Approval Option**: Users can press the ✅ at the bottom left of the card to approve the claim for use. Upon approval, users have the option to specify a limited approval or standing approval for future use. * **Resolve**: Closes the card and removes it from the review queue.
**Optimizing Claim Review Best Practices** The number of claims that need full review can drop by as much as 80% per document when * **Approval Process**: By approving claims in the sidebar, reviewers contribute to the Decision Store for approved marketing materials and ensure compliance with legal standards. The approval process enables collaboration between legal and marketing teams, fostering a culture of transparency and accountability. * **Content Scanning**: During onboarding, enterprises will have their content scanned for previously approved claims. Regular scanning of approved materials expands the Decision Store further, which highlight more claims that may have had past approvals. The Claims feedback feature in Protege empowers users to evaluate and approve claims with confidence, ensuring compliance with advertising regulations and mitigating potential legal risks associated with misleading statements. By leveraging feedback and collaboration tools, users can streamline the review process and promote alignment between legal and marketing objectives effectively. # Comment Generator Each Card has a 💬 button that creates leads to the Comment Generator. This builder is designed to make writing comments for a marketer fast and easy. When the Comment Generator is opened from a card, you will see: * **Text to Highlight and Comment on** - this is the original text that is being discussed. Included on all feedback types. * **Explanation** - The concern or warning for that text. Included on all feedback types. * **Suggestions (if appropriate)** - Drop in alternative text for a Product Claim or Policy Feedback. be included. Included on Product Claims and select Policy Feedback Cards. * **Similar Claims (if appropriate)** - For Claims, if there are medium or high match statements, they can be copied the marketer to see. Check the explanations, suggestions, and similar claims you want to include in the comment. The text box will include the text that you can copy-paste. On a Mac, you can **\[apple key] + C** to copy. Press add a comment in Google Doc **\[apple key] + option + M** over the relevant text, and then paste **\[apple key] + V.** ![](/files/W4uRZugCWjAwMXA8L5ti) **Note:** Direct commenting into the Doc from the Protege sidebar is not supported due to Google API limits. A workaround is being developed. # Conducting Reviews #### Reviewing Documents in Protege AI *** **Overview** Protege AI offers multiple platforms and integrations for reviewing documents efficiently. Users can leverage the robust capabilities of Protege AI across different environments to review documents, including direct interfaces and popular office software integrations. This flexibility ensures that users can access AI-driven feedback and insights regardless of their preferred workflow tools. **1. Protege AI Dashboard** The Protege AI Dashboard is the central hub for document reviews, providing a comprehensive interface where various types of attachments can be analyzed. **Features:** * **Support for Multiple Attachments**: Users can upload images, PDF files, and Frame.io videos directly onto the dashboard. * **Integrated AI Feedback**: Alongside the displayed documents, the dashboard provides AI-generated feedback, highlighting areas of concern, suggesting improvements, and pointing out compliance issues. **2. Google Docs and Slides** Integration with Google Docs and Slides allows users to receive real-time feedback while working within Google's collaborative environment. This integration is seamless, offering a direct overlay of AI insights as users edit or review documents and presentations. **Features:** * **Real-Time Feedback**: As users work on their documents and presentations, Protege AI offers instant suggestions and corrections directly within the interface. * **Seamless Integration**: This feature works without disrupting the native functionalities of Google Docs and Slides, making it an intuitive extension to the Google workspace. **3. Office 365 Word (Desktop and SharePoint)** Protege AI extends its capabilities to Microsoft Office 365, specifically within Word for Desktop and SharePoint environments. This integration ensures that users entrenched in Microsoft ecosystems can also benefit from AI-driven document analysis. The features are identical to the Google Docs and Slides above. *** Each of these methods offers unique advantages, catering to different user preferences and operational environments. By providing diverse platforms for document review, Protege AI ensures that its powerful analytical tools are accessible wherever users choose to work, enhancing both individual productivity and organizational compliance. # Protege AI Dashboard **Prerequisite:** [Task Manager Setup](/review/getting-started/task-manager-setup) **Overview** Protege AI provides a streamlined approach to review and manage feedback on various types of document attachments. Whether dealing with video files, PDFs, images, or text documents, Protege AI ensures that feedback is accessible and actionable within the context of each user's workflow. **Accessing Attachments and Feedback** To access and review feedback on attachments, users should navigate to the specific task where these files are linked. Here's how feedback is managed across different types of attachments: **1. Frame.io Videos, PDFs, and Images** Attachments such as videos, PDFs, and images are easily accessible within the tasks where they are stored. Feedback on these files is integrated directly into the Task Manager ticket, ensuring that all comments and suggestions are centralized and traceable. **Features:** * **Integrated Feedback in Task Manager**: Comments from PDFs and images are left directly in the task management tool (e.g., Asana Task), which consolidates feedback with task specifics. * **Timestamped Video Comments**: For videos hosted on Frame.io, comments can be attached to specific timestamps. This feature allows users to view feedback at the exact relevant moment in the video, enhancing the clarity and relevance of the feedback.
**2. Google Docs, Slides, and Word Files** For text documents created in Google Docs and Microsoft Word, Protege AI offers a preview of the AI-generated feedback directly within these platforms. However, it is recommended that you access the feedback directly from the Protege AI application for a richer editing experience **Best Practices:** * Preview. Use the Task Manager's File Preview to assess the time required to review the ticket * Move back to Native Applications. Users will see the full AI feedback and editing features in Google Docs, Slides, or Office 365 Word, allowing immediate action on issues and suggestions. *** By utilizing Protege AI’s File and AI Feedback Preview, users can provide comments and feedback to raw image and video files without switching application. # Google Docs, Slides **Prerequisite:** [Google Workspace](/review/getting-started/document-editor-installation/google-workspace) **Open**: **the Plug-In:** 1. Create a new Google Document and enter the text you want reviewed. Alternatively, you can open an existing Google Document. 2. Navigate to the Extensions tab, select "Protege AI", and then select "Open".
**Log In:** If you haven't logged in previously, you'll be prompted to do so at this point. After opening the PRotege AI extension, press "Sign In". Enter your credentials. Once logged in, you'll have full access to existing feedback for that document or create a new document for scanning. **Setting the Document Review Type:** When a new document is opened for review, setting the document review type is a process designed to tell the AI which evaluation to do for your content. You'll be prompted to put the name of the document and the Document Review Type that is set up for the company. The name of the document will be used to create an associated task for your team's progress tracking. **Change** **the Document Review Type:** You can change the Document Review Type by pressing the ⚙️ icon on the sidebar, and selecting "Edit Project." After that press Quick Scan again to see the new feedback. For a better understanding of Document Review, see [Document Review](/review/review-tool-concepts/document-review), **Scan Process and Processing Feedback:** The scan process in Protege Counsel is a comprehensive evaluation mechanism designed to identify and mitigate legal risks associated with your content. From the sidebar in a document, run Quick Scan to get the results of the evaluation. Depending on the length of the document, it may take several seconds to start seeing the feedback populate.\ \ There are three categories of Feedback: {% content-ref url="/pages/vjqJow3hM4SOLNs70pBB" %} [Product Claims](/review/review-tool-concepts/document-review/feedback-cards/product-claims) {% endcontent-ref %} {% content-ref url="/pages/GstMKCAWDyjJT6SFPQCf" %} [Trademarks](/review/review-tool-concepts/document-review/feedback-cards/trademarks) {% endcontent-ref %} {% content-ref url="/pages/oiQVzM4RBBcRgzRD7qgG" %} [Policy Feedback](/review/review-tool-concepts/document-review/feedback-cards/policy-feedback) {% endcontent-ref %} For more info on how the Scans are done, see [Policy Engine](/review/review-tool-concepts/document-review/policy-engine). **Text Highlighting:** By default Protege will highlight the text in the doc that have a potential issue flagged in the Product Claims, Trademarks, and Policy Feedback cards. You can remove and reapply the highlighting at any time by pressing the button shown at the top of the nav bar. ![](/files/byV2UzrcovAvBi4Hx7Cz) **Limitations**: The extension has been tested for Google Docs up to 25 pages long and Google Slides up to 100 slides long. If you have content to review above those limits, please reach out to support to enable very long documents. # Office 365 Word **Prerequisite:** [Office 365](/review/getting-started/document-editor-installation/office-365) **Open**: **the Plug-In:** 1. Create a new Word Document and enter the text you want reviewed. Alternatively, you can open an existing Word Document. 2. Navigate to the Home Ribbon tab, select "Add In", and "Protege AI".
**Log In:** If you haven't logged in previously, you'll be prompted to do so at this point. After opening the Protege AI extension, press "Sign In". Enter your credentials. Once logged in, you'll have full access to existing feedback for that document or create a new document for scanning. **Setting the Document Review Type:** When a new document is opened for review, setting the document review type is a process designed to tell the AI which evaluation to do for your content. You'll be prompted to put the name of the document and the Document Review Type that is set up for the company. The name of the document will be used to create an associated task for your team's progress tracking. **Change** **the Document Review Type:** You can change the Document Review Type by pressing the ⚙️ icon on the sidebar, and selecting "Edit Project." After that press Quick Scan again to see the new feedback. For a better understanding of Document Review, see [Document Review](/review/review-tool-concepts/document-review), **Scan Process and Processing Feedback:** The scan process in Protege Counsel is a comprehensive evaluation mechanism designed to identify and mitigate legal risks associated with your content. From the sidebar in a document, run Quick Scan to get the results of the evaluation. Depending on the length of the document, it may take several seconds to start seeing the feedback populate.\ \ There are three categories of Feedback: {% content-ref url="/pages/vjqJow3hM4SOLNs70pBB" %} [Product Claims](/review/review-tool-concepts/document-review/feedback-cards/product-claims) {% endcontent-ref %} {% content-ref url="/pages/GstMKCAWDyjJT6SFPQCf" %} [Trademarks](/review/review-tool-concepts/document-review/feedback-cards/trademarks) {% endcontent-ref %} {% content-ref url="/pages/oiQVzM4RBBcRgzRD7qgG" %} [Policy Feedback](/review/review-tool-concepts/document-review/feedback-cards/policy-feedback) {% endcontent-ref %} For more info on how the Scans are done, see [Policy Engine](/review/review-tool-concepts/document-review/policy-engine). **Text Highlighting:** By default Protege will highlight the text in the doc that have a potential issue flagged in the Product Claims, Trademarks, and Policy Feedback cards. You can remove and reapply the highlighting at any time by pressing the button shown at the top of the nav bar. ![](/files/byV2UzrcovAvBi4Hx7Cz) **Limitations**: The extension has been tested for Protege AI up to 25 pages long and Google Slides up to 100 slides long. If you have content to review above those limits, please reach out to support to enable very long documents. # Automated Actions After a document review is completed, Protege AI can perform various automated actions to streamline your workflow based on user-defined risk thresholds. ## Overview Automated actions eliminate manual steps by automatically responding to review results. Actions are triggered when policy feedback meets specific risk criteria that you define. For example, if a review identifies fewer policy violations than your threshold, the document can be automatically approved without manual intervention. Conversely, if high-risk issues are detected, detailed comments can be automatically posted to your task management system. ## Available Actions ### Auto-Approval If the identified risks are below your user-defined auto-approval threshold, documents can be automatically approved, eliminating the need for manual review. **Benefits:** * Speeds up review cycles for low-risk content * Reduces reviewer workload on routine changes * Maintains consistency in approval criteria * Ideal for minor updates to previously approved content **Use Cases:** * Small changes to marketing assets * Updates to previously reviewed materials * Content with minimal or no policy violations * Routine template-based documents ### Auto-Comment Generation The AI can automatically generate and add comments to your task management system for issues identified during the review. **Features:** * Detailed insights about each policy violation * Suggested actions for remediation * Risk level indicators (High, Medium, Low) * Links back to specific feedback in Protege When identified risks exceed your threshold, all problems are consolidated and posted as a comment in the requester's ticket, ensuring that high-risk issues are promptly flagged and addressed. ## Configuration ### Setting Up Automated Actions 1. Navigate to the **Task Manager** where you want to enable automated actions 2. If there is no Default Evaluation Type set, select one to run on the Task Manager 3. Toggle on **Autocomment** and/or **Autoapprove** based on your workflow needs 4. Click the ⚙️ icon to configure individual policy thresholds for each action 5. Define risk levels and occurrence counts for each policy type 6. Press ✔️ to save your settings ### Configuring Thresholds For each policy in your evaluation: * Set the **risk level** threshold (High, Medium, Low) * Define the **occurrence count** that triggers the action * Different thresholds can be set for auto-approval vs. auto-commenting **Example Configuration:** * Auto-approve if: 0 High risk, ≤2 Medium risk, any Low risk * Auto-comment if: ≥1 High risk, ≥5 Medium risk ## Action History View a complete history of all automated actions: 1. Go to **Settings** → **Action History** 2. Review past auto-approvals and auto-comments 3. Filter by date, project, or action type 4. Audit automated decisions for compliance purposes ## Best Practices * **Start Conservative**: Begin with strict thresholds and gradually relax them as you gain confidence * **Regular Review**: Periodically review action history to ensure thresholds remain appropriate * **Policy-Specific Settings**: Configure different thresholds for different policy types based on risk * **Team Alignment**: Ensure your team understands which documents will be auto-approved * **Audit Trail**: Maintain records of threshold changes for compliance purposes ## Integration with Task Managers Automated actions work seamlessly with: * Asana * Jira * Smartsheets * Wrike Comments and approvals are posted directly to tickets in your connected task management system, maintaining a complete audit trail. ## Disabling Actions To temporarily or permanently disable automated actions: 1. Return to your Task Manager settings 2. Toggle off **Autocomment** or **Autoapprove** 3. Save your changes Previous action history is preserved even when actions are disabled. # Decision Store The Decision Store in Protege AI acts as a centralized, dynamic repository for all marketing language, claims, and trademarks previously used or reviewed. It provides legal and compliance teams with a consistent and efficient way to track, manage, and reuse approved content while identifying potential risks. When Protege scans public pages or reviews documents, it can automatically add observed claims and trademarks to the Decision Store—even if those items weren’t explicitly approved. By default, these entries are marked as “In-Use”, indicating they are active within your content environment. **Approval Categories:** Protege allows teams to customize how content is classified and approved. Categories include: * Proprietary: Trademarks and brands that belong to your company. During onboarding, the Customer Success team will tag a set of proprietary marks. These skip permission checks in reviews and are automatically resolved in scans. * Standing Approvals: Claims or trademarks with full approval and no restrictions. These are shown only once per document, on the first instance of use. * Limited Approvals: These approvals include specific restrictions, such as requiring customer consent before use. They can also be set to expire—for example, after an event or partnership ends. Expiration dates can be configured during approval (via the Protege Extension) or later in the Dashboard. **Claims Management:** In the Claims section of the Decision Store, users can: * View claims grouped by semantic similarity: * High Match – Closely aligns with a previously reviewed claim. * Medium Match – Moderate similarity. * Low Match – Minimal similarity; shown primarily for awareness. Each claim is tracked independently. For instance, if the statement *“Apples have 3 times the sugar of oranges”* appears in three documents, but only one version has a standing approval, then: * That instance is marked as Approved * The other two are shown as In-Use **Claim Disclosure Requirements** You can also associate required disclosures with any approved claim. Once a disclosure is linked: * Protege will automatically verify that the necessary disclosure appears any time the claim is reused in a scanned page or reviewed document. * If the disclosure is missing or altered, the system will flag it for compliance review. **Trademarks Management:** The Trademarks section provides a consolidated view of all trademark appearances—whether found on scanned public pages or in reviewed documents. This enables teams to monitor brand usage, spot inconsistencies, and ensure compliance across all marketing channels. **Initial Set Up of the Decision Store** To get started with the Decision Store: 1. Identify public-facing pages that have gone through legal review. 2. Follow the process to [Create a New Job](/review/content-scanning/create-a-new-job) in the Content Scanner. Ensure “Save Feedback in Decision Store” is turned on. This will ensure all identified claims, policy feedbacks, and trademarks are logged from the start.
**On Going Maintenance of the Decision Store** Reviewers can provide explicit approvals by marketing Claims, policy feedback, and trademarks with one of the specific **Approval Categories.** In addition, you can continuously keep your Decision Store updated with "In-Use" statuses: 1. Go to the Marketing Tasks section in the Protege sidebar. 2. Click Settings. 3. Locate your primary Approval Board. 4. Enable the setting: “Save in Decision Store Feedbacks from Completed Document Reviews.” This will automatically capture and store approved language, claims, and trademark feedback from every reviewed marketing document—keeping your compliance records current and centralized.
# Brands & Attributes ### 🔍 Overview: Brands and Attributes in Protege AI Brands and Attributes in Protege AI empower you to fine-tune how compliance Policies are applied during the review process. By using these configurable elements, you can customize the behavior of Protege’s AI engine to respond to your organization’s specific regulatory and operational needs. These tools help ensure that the correct policies are triggered based on the context of the content being reviewed—whether it’s associated with a specific brand, marketing channel, product type, or location (states or countries). *** ### 🏷️ Brands Brands represent the distinct brand identities your organization markets or manages. These are typically aligned with product lines, subsidiaries, or customer-facing entities. When a Brand is associated with a piece of content, Protege AI can tailor its policy application and compliance checks to reflect the rules relevant to that specific brand. For example: * *Brand A* might be governed by stricter regulator guidelines. * *Brand B* might be subject to standard internal review processes. #### Key Use Cases: * Applying different policies for different business units. * Separating rulesets for regional vs. global brands. * Controlling risk exposure per brand identity. *** ### 🧩 Attributes Attributes allow you to define customizable metadata fields that provide additional context to the content being reviewed. Attributes are essential for creating dynamic, conditional policy logic. #### Each Attribute consists of: * Field Name A unique identifier for the Attribute. This is how Protege AI references the Attribute when applying policies or processing reviews. * Accepted Values A list of predefined, selectable values that describe the possible states or categories for that Attribute. These can be customized to suit your internal terminology or review logic. #### Example: Attribute: state Accepted Values: CA, NY, WA Policies can then be configured to behave differently depending on whether the content is intended for a specific state. #### Common Attribute Use Cases: * Marketing Channel (e.g., Digital vs. Out of home) * Product categories (e.g., checking accounts, treasury accounts, crypto) * Region or jurisdictional targeting (e.g., nationwide, CA, NY) *** ### ⚙️ How Brands and Attributes Work Together Together, Brands and Attributes allow for: * Precise policy targeting: Trigger only the relevant compliance checks. * Streamlined operations: Avoid over-reviewing by applying the right policies to the right content. * Scalability: Manage complex organizations with diverse product and brand portfolios. By leveraging these features, teams can significantly enhance their compliance workflows and ensure policy logic remains context-aware and adaptable. # Setting Up Brands Follow these steps to create and manage Brands in Protege AI: 1. Navigate to Settings from the main menu. 2. Select Brands from the sidebar. 3. Click on Add Brand in the Brands configuration page. 4. Enter the Brand Name — this should match the brand identity as used in your organization’s marketing or compliance structures. 5. Click Save to create the Brand.
# Setting Up Attributes ### Setting Up Attributes 1. Go to Settings from the main menu. 2. Select Attributes from the sidebar. 3. On the Attributes configuration page, click Create New. 4. Enter a Field Name — this serves as the unique identifier for the Attribute. 5. Define the Accepted Values — a list of predefined options that users can select when tagging content. 6. Click Save ✔️ to finalize and make the Attribute available for use in reviews and policy logic.
### Using Dynamic Step Execution with Attributes Dynamic Step Execution enhances policy flexibility by automatically referencing and applying content from a linked database based on Attribute values. This is especially useful for regulatory scenarios that vary by region, product type, or audience. #### How It Works: * Condition-Based Matching: Each condition (e.g., a U.S. state, audience type, or product category) can have its corresponding regulatory statement stored in a linked database file — one entry per row. * Automatic Text Retrieval: When a review is triggered, Protege AI replace a **variable** in the prompt with the content’s Attribute values (e.g., State = California) and fetches the relevant disclosure or text from the database file. * One Policy, Many Conditions: Instead of creating multiple policies for each variation, you can configure a single dynamic policy that checks the database and applies the appropriate rule or disclosure based on context. #### Example: If a product has different disclosures required for California, Texas, and New York: * You store each disclosure in the database under the respective state. * The dynamic step automatically retrieves and applies the correct disclosure based on the State Attribute assigned to the content. This approach reduces duplication, simplifies policy management, and ensures compliance with varying regulatory requirements — all within a single, efficient policy structure. {% content-ref url="/pages/dmOCy6kNrGdmbkYkPlmb" %} [External Databases for Attributes](/review/review-tool-concepts/brands-and-attributes/setting-up-attributes/external-databases-for-attributes) {% endcontent-ref %} {% content-ref url="/pages/WCrDQhrRwnMSS3yjDBw2" %} [Add Variables to Steps](/review/review-tool-concepts/brands-and-attributes/setting-up-attributes/add-variables-to-steps) {% endcontent-ref %} # External Databases for Attributes 1. **Set up an external spreadsheet.** An external database refers to a spreadsheet containing combinations of attributes and designated languages. Format the spreadsheet with each Attribute as a separate column, and include a final column labeled Text. In the Text column, specify the replacement text, such as required disclosures for that combination of attributes. This is an example of the format for an environment with Attributes *product* and *state*.
2. **Add the Spreadsheet as a Database**. Go to Settings and select Attributes. In the Linked Database section, click Link New File. 3. Enter the Google Sheet link and assign a specific **variable** name. This variable will be used in policies to refer this database. 1. Ensure Protege AI has Google Workspace access. If you haven’t done this yet, follow[ these instructions](/review/getting-started/document-editor-installation/google-workspace) if you have not.
4. When completed, the Linked File should show under the Linked Databases section.
# Default Brand Attributes 1. **Set up an external spreadsheet.** An external database refers to a spreadsheet containing combinations of attributes and designated languages. Format the spreadsheet should be a first column labeled Brand, and then each Attribute as a separate column. In the Brand column, specify the brand that's already been inputted in PRotege. This is an example of the format for an environment with Attributes *product* and *state*.
1. **Add the Spreadsheet as a Database**. Go to Settings and select Attributes. In the Linked Database section, click Link New File. 2. Enter the Google Sheet link and assign variable "**Brand Defaults**". This variable will be used in policies to refer this database. 1. Ensure Protege AI has Google Workspace access. If you haven’t done this yet, follow[ these instructions](/review/getting-started/document-editor-installation/google-workspace) if you have not.
4. When completed, the Linked File should show under the Linked Databases section.
# Add Variables to Steps When using linked files (like your Attributes or regulatory databases), Protege AI automatically creates variables you can insert into policy steps for dynamic, context-aware reviews. These variables can be used in multiple fields within a step, including: * Explanation * Prompt * Keywords #### To Add a Variable: 1. In the step editor, place your cursor in the field where you’d like to insert the variable (e.g., Explanation).
1. Press the $ key to open the list of available variables. 2. Select the appropriate variable from the dropdown list — this variable pulls matching data from the linked file. 3. Once inserted correctly, the variable name will turn green, indicating it’s properly connected.
# Real-Time Policy Assignment #### Configuring Policy Allowlist for Specific Tasks Policies can be applied only to Tasks with specific attributes. For example, if there is a policy that should only apply to marketing tasks in California and New York, you can set the allowlist to include only those states. To configure this: 1. Go to the Policy you wish to modify. 2. Edit the **Attribute Allowlist** section to specify the attributes that must be matched for the policy to apply. You can add both **Brands** and **Attributes** in this section
# Use in Content Scanning Job ### 📝 Using Brands and Attributes in Content Scanner Jobs When creating a new Content Scanner Job, you can assign a Brand and one or more Attributes to tailor the policy execution to the context of the content being scanned. #### ✅ How It Works: * Brand Selection The Brand is chosen from a dedicated section in the job setup form. This defines the overarching identity (e.g., product line, business unit) that the content belongs to. * Attributes Assignment In the Attributes section, you define key context elements by selecting Field–Value pairs. For example: * Channel = SocialMedia * Region = US * ProductCategory = Serum These inputs influence how Protege AI determines which Policies to apply during the scan. #### 🎯 Why It Matters: Protege AI uses the assigned Brand and Attributes to: * Dynamically select and execute the appropriate policies. * Ensure regulatory rules are matched to the correct context. * Improve precision and reduce unnecessary alerts. This makes every scan more accurate and context-aware — especially useful for content spanning multiple markets, products, or audience types.
# Use in Tasks ### 🔄 Auto-Detecting and Editing Attributes from External Platforms When a Task is scanned from an integrated platform like Jira or Asana, Protege AI will automatically attempt to detect and assign Attributes based on the content of the ticket. #### 🧠 Automatic Detection If your task's description includes recognizable values that match your configured Attributes (e.g., marketing channel, region, or product), Protege AI will auto-populate those values during the scan setup. For example: * If a Jira ticket includes the phrase “For use in CA for sportsbook” Protege AI may assign: * state = CA * product = sportsbook #### ✏️ Manual Reassignment If: * No attributes were detected, or * You want to override or refine the detected values, You can do so in the Attributes section of the Content Scanner Job setup.
Just select the appropriate Field–Value pairs to ensure the task is reviewed with the right policy context.
# Teach your AI This is in Public Beta for Enterprise plans. Protege AI continuously evolves our core AI system to provide smarter, more efficient tools for managing compliance. These tools enhance feedback workflows, streamline policy updates, and offer tailored AI solutions for unique use cases. {% content-ref url="/pages/xVKfFTUuIFLmW1MgZlI6" %} [Customize Feedback Behavior](/review/review-tool-concepts/teach-your-ai/customize-feedback-behavior) {% endcontent-ref %} {% content-ref url="/pages/pxYFpnQ9hHYHNtcBykZG" %} [Feedback, Model Retraining, and Benchmarking](/review/review-tool-concepts/ai-features-and-model-management/feedback-model-retraining-and-benchmarking) {% endcontent-ref %} # Customize Feedback Behavior This is in Public Beta for Enterprise plans. Protege Policy Feedback helps streamline policy compliance by identifying potentially risky content and allowing you to take actions. Here’s how to manage feedback cards and train your AI model for greater precision: ### AI-Powered Feedback Card Actions When a policy flags text that your organization deems **not** risky or out-of-scope, you have eight primary actions:
OptionExplanationExample Usage for "Free Stuff" Policy
✅ Resolve (Dismiss feedback)Removes this specific feedback instance and prevents the exact same text from being flagged again on this page or document. Use this when the flagged content is acceptable for a specific context or time period.If "free AirPods with every purchase" appears in ad copy during a legitimate limited-time promotion, resolving it acknowledges the content is appropriate for now.
👍 Thumbs UpRetrains the model to continue flagging this type of content more consistently. Use when the AI is under-flagging similar items and you want it to learn to catch them reliably.If the model inconsistently identifies free item language, giving a thumbs up to correctly flagged examples helps improve the model's detection accuracy.
🔘 AcknowledgeTags you as the user to this feedback card while keeping the item visible in the Content Scanner until you or another user clicks Resolve. Use this when additional review or confirmation is needed before taking action.If a reviewer needs to verify details like the expiration date of a promotion stating "free AirPods with every purchase until 7/31," you can acknowledge it and return later with complete information.
🚫 Ignore Phrasing for EverythingRetrains the model to ignore this specific phrasing for this policy across the entire environment through fine-tuning. Use when the flagged content is clearly not a violation of the intended policy.If "low cost platform" was flagged under a free items policy, this action teaches the model that such phrasing doesn't constitute free item language.
🚫 Ignore Phrasing for BrandIgnores all instances of this exact phrasing for this policy across any of the brand's marketing content using text-search filtering. Use for permanent brand-specific language that should never be flagged.If a financial services brand offers "free wire transfers" as a standard service feature, this action prevents future flags of that exact phrase.
🚫 Ignore Policy for BrandSuppresses all future flags from this policy for the specified brand only. Use when an entire policy doesn't apply to a particular brand's business model.If your Protege environment manages multiple brands and one brand's entire product offering is free, this action disables the policy for that brand specifically.

If you have a single brand in Protege, you would disable the Policy in the Policy Engine instead.
🚫 Ignore Policy for PageSuppresses all future flags from this policy for this specific page or document only.Use when a policy should never run on certain page types again. This is commonly applied to Terms of Service and Privacy Policy pages where policy flags are typically not relevant to the content's purpose.
🚫 Wrong PolicyIndicates that the flagged text actually falls under a different policy category. Retrains the model to learn proper policy-to-text mappings and improve classification accuracy.If the free items policy flagged "highest payout sports betting platform in the USA," this action would reclassify it under unqualified claims policy instead, since it's not about free offerings but rather unsubstantiated comparative claims.
Below is a visual example showing where each action button appears on the Feedback Card. The labels correspond to the table above:
## Add New (Manual Missing feedback) Allows users to explicitly enter any missing feedback—non-flagged examples—to Teach the AI and improve its detection accuracy.
## Teach your AI Admin Approvals By default, every Teach your AI submission enters a pending state and must be manually approved through the Policy Engine before being used for model training. This creates a human-in-the-loop validation step that maintains training data quality. #### Approval Workflow 1. **Submission**: When users submit a Teach your AI example, it is automatically queued for review 2. **Review**: Designated approvers can access pending submissions in the Policy Engine 3. **Decision**: Approvers can take one of three actions: * **Approve**: Accept the submission for model training * **Edit**: Modify the submission before approval * **Delete**: Remove the submission entirely 4. **Training**: Only approved submissions are included in the model finetuning process #### Managing Submissions **Editing Submissions** * Click on any pending submission to open the editor * Modify the instruction text, expected output, or formatting * Save changes to update the submission while maintaining its place in the approval queue **Deleting Submissions** * Select submissions that are inappropriate, duplicate, or no longer needed * Deleted submissions are permanently removed and will not be used for training ### Auto-Approval Feature #### 3-Day Auto-Approval For teams that need faster iteration cycles, you can enable automatic approval after a 3-day waiting period: 1. Navigate to Policy Engine settings 2. Enable "Auto-approve Teach your AI after 3 days" 3. Configure notification preferences for pending approvals **How Auto-Approval Works:** * Submissions remain in pending status for 3 days * If no manual action is taken within this timeframe, they are automatically approved * Manual approval or rejection can still occur at any point during the 3-day window * Auto-approved submissions are logged for audit purposes ### Key Notes * **Fine-tuning Beta**: The **“Thumbs Up”** (👍), **Wrong Policy**, and **Ignore Phrasing for Everything** workflows rely on large language model fine-tuning. * **Audit Trail**: Every action (Resolve, Acknowledge, Wrong Policy, Thumbs Up, Ignore Phrasing/Policy) is recorded in the review history for compliance auditing. # AI Features & Model Management Protege AI offers sophisticated artificial intelligence capabilities that go far beyond basic content review. Our platform provides enterprise-grade AI model management, custom training workflows, and advanced multi-modal analysis capabilities. ### Key Capabilities #### 🧠 **Multi-Model Architecture** * Support for variety of privately hosted AI models including Llama #### 🎯 **Custom Model Training** * Fine-tune models on your organization's specific compliance requirements * Create domain-specific agents for specialized review tasks * Validate model performance against your historical decisions #### 📊 **Performance Benchmarking** * Comprehensive model evaluation and comparison * A/B testing capabilities for model performance * Historical accuracy tracking and improvement metrics #### 👁️ **Vision AI Capabilities** * Advanced image and video content analysis * OCR text extraction with context awareness * Multi-frame video processing for comprehensive review #### 🔄 **Continuous Learning** * Feedback-driven model improvement * Automated retraining workflows * Performance monitoring and alerting ### Getting Started This section is available for **Enterprise plans** and requires initial setup by the Protege AI team. Contact your account manager to enable advanced AI features. # Model Selection & Configuration Protege AI's AI system allows you to change the default AI model for your content type and review requirements. Our proprietary ShieldLlama model, combined with specialized options, provides optimal accuracy for compliance review. ### Configuration in Policy Steps Model selection is simplified - the system handles complexity automatically: #### **Policy Step Setup** 1. Navigate to **Policy Engine** → **Your Policy Group** → **Edit Step** 2. **Model Configuration** section shows: * **Primary Model**: Automatically selected (typically ShieldLlama) * **Specialized Options**: Available if needed for your content type * **Vision Processing**: Auto-enabled when there is a Prompt in Vision Prompt
### Available Models #### **Recommended: ShieldLlama (Proprietary)** Our flagship model, optimized specifically for compliance and content review: * **Best for**: All standard compliance, marketing review, and policy enforcement * **Advantages**: Purpose-built for your use cases with superior accuracy, trainable with Teach your AI * **Performance**: Fastest processing with highest precision for compliance content * **Default choice**: Automatically selected for most review scenarios #### **Specialized Models** **Qwen 235 A22B Instruct** * **Best for**: Large document processing (emails, lengthy reports, multi-page documents) * **Advantages**: Exceptional handling of long-form content and complex document structures * **Use cases**: Employee email review, comprehensive document analysis, multi-section policy documents **Llama 3.3 70B** * **Best for**: Reasonable processing requiring specific logic * **Advantages**: Superior analytical capabilities for nuanced policy interpretation * **Use cases**: Edge case analysis, complex regulatory interpretation, multi-step compliance decisions **Llama Maverick & Scout** * **Maverick**: Advanced general-purpose model with broad capabilities * **Scout**: Optimized for rapid initial screening and triage * **Use cases**: Custom workflows requiring specific processing characteristics #### **Vision Models** **Llama Maverick Vision (Default)** * **Automatically selected** for all image and video content * **Capabilities**: Image analysis, OCR, visual content compliance review * **Handles**: Screenshots, marketing images, social media content, document scans **Specialized Vision Models** * Available on request for specific use cases * Contact support to enable advanced vision capabilities * Custom configurations for industry-specific visual content ### Model Recommendations by Use Case #### **Standard Marketing Review** ✅ **ShieldLlama** (Default) * Social media posts * Marketing copy * Website content * Advertising materials #### **Employee Communication Review** ✅ **Qwen 235 A22B** (Recommended for large documents) * Email chains and threads * Internal communications * Lengthy reports and memos * Multi-page documents #### **Complex Policy Decisions** ✅ **Llama 3.3 70B** * Edge case interpretation * Multi-step compliance analysis * Regulatory gray areas * Appeals and escalations #### **Visual Content Review** ✅ **Llama Maverick Vision** (Default) * Marketing images * Social media visuals * Document screenshots * Video content frames #### **High-Volume Screening** ✅ **ShieldLlama** + **Scout** * Bulk content processing * Initial triage and filtering * Real-time content monitoring * Automated compliance checks ### # Feedback, Model Retraining, and Benchmarking This is in Public Beta for Enterprise plans. ### Feedback and Counterfactual Example Generation When users submit feedback through the **"Teach Your AI"** feature, that feedback is processed using a specialized reasoning large language model. This model creates hypothetical examples based on your feedback, a method known as **counterfactual generation**. Counterfactual generation involves imagining "what-if" scenarios by altering small parts of a given example to test and improve the model's understanding. Importantly, **your exact feedback is not directly used** to train your model. Instead, the AI generates new hypothetical examples inspired by your input. Both your original feedback and the hypothetical examples **are kept private** and **are not shared** with Protege's general **ShieldLlama** model. ### Model Retraining Process * Models are **retrained nightly at midnight Pacific Time** on working days. * If a newly trained model **exceeds the benchmark** set by the prior model, it will **be automatically promoted** to active use. ### Benchmarking and Performance Measurement To ensure quality improvements, we use **multiple types of benchmarks**: #### 1. Policy Annotation Set These are real-world examples where users have labeled AI feedback as incorrect. The model is tested against these annotations to ensure it better captures such cases over time. #### 2. Test Set A portion (10%) of the synthetically generated dataset, based on user examples, is held out of the training process. This "test set" is used to objectively measure model performance on unseen data. #### 3. Confusion Matrix We also analyze model results using a **confusion matrix**, which breaks down predictions into four categories: * **True Positive (Green Box):** Correctly identified errors. * **True Negative (Green Box):** Correctly ignored non-errors. * **False Positive (Red Box):** Incorrectly flagged something as an error. * **False Negative (Red Box):** Missed identifying a true error. The goal is to maximize values in the **green boxes** (true positives and true negatives) while minimizing values in the **red boxes** (false positives and false negatives).
### Model Versions and Update Numbering #### Minor Version Updates Version updates that are specific to your environment are reflected through minor number increments. For example, in version **10.0.0 to 10.0.1**, the last digit would increase with each minor update that come from Teach your AI fixes. #### Major Version Upgrades (Model Rebasing) On a regular cadence, Protege will perform **model rebasing**, updating your model with the latest ShieldLlama model that includes policies, precedents, and compliance standards observed across industries (e.g., FTC, NAD, FDIC, and more). These substantial updates are reflected in **major version upgrades** (e.g., moving from version 10.0 to 11.0, the first digit). To set up a fine-tuned model for your organization, reach out to . # Monitoring Protege AI offers a comprehensive web monitoring system designed to assist lawyers and legal teams in managing legal risks associated with online content. This feature allows users to set up scans for any website associated with their brand at a cadence of their choice. The scanned content can then be utilized to build out the Decision Store, facilitating faster approval of "In-Use" claims and trademarks during future reviews. Moreover, the scanning function can be employed to monitor lower-tier marketing content channels that may not be regularly reviewed by legal, such as blogs and release updates, ensuring compliance across all online platforms. **Key Features:** 1. **Customized Scanning:** * Set up scans for any website related to your brand according to your preferred cadence. * Tailor the scanning frequency to meet your specific monitoring needs and regulatory requirements. 2. **Decision Store Integration:** * Utilize scanned content to populate the Decision Store with "In-Use" claims and trademarks. * Streamline future reviews by expediting the approval process with pre-populated data from website scans. 3. **Comprehensive Compliance Monitoring:** * Extend monitoring beyond primary marketing channels to include lower-tier platforms like blogs and release updates. * Ensure compliance across all online content channels, minimizing the risk of regulatory violations or legal disputes. # Platforms Supported Below is a list of platforms supported by Protege AI for compliance monitoring and content evaluation. From social media channels to app store listings, our platform helps ensure compliance remediation and analysis across all major digital spaces to keep your brand compliant and secure. | Platform | Status | | ------------------------- | -------------------- | | Apple App Store Listing | Supported | | Discord | Available by Request | | Facebook | Supported | | Instagram | Supported | | Google Play Store Listing | Supported | | LinkedIn Company Page | Supported | | Reddit | Available by Request | | TikTok | Supported | | X | Supported | | YouTube | Supported | | 小红书 - Little Red Book | Available by Request | #### Note: * If you would like to inquire adding a new platform, please don't hesitate to contact our support team at . We're here to assist you throughout the process. # Create a New Job Protege Content Scanner pages allows you to create, schedule, and manage content scanning jobs for compliance monitoring and evaluation. Easily configure scans by selecting platforms, setting parameters, and adding custom attributes to tailor the analysis to your needs. Monitor the status and results of each job in one centralized dashboard, ensuring comprehensive oversight and seamless compliance workflows. **Create a Job for:** {% content-ref url="/pages/oak6c3G5PtHPydhJPoBp" %} [Proprietary Content](/review/content-scanning/create-a-new-job/proprietary-content) {% endcontent-ref %} {% content-ref url="/pages/Cu9wsKGhbSDRapV7Fqgu" %} [Third Party - Influencer and Affiliates](/review/content-scanning/create-a-new-job/third-party-influencer-and-affiliates) {% endcontent-ref %} #### Note: * If you encounter any issues or have questions about managing monitoring jobs, please don't hesitate to contact our support team at . We're here to assist you throughout the process. # Proprietary Content 1. **Navigate to the Content Scanner Page** \ To begin, log in to the [Protege AI platform](https://app.tryprotege.com) using your credentials. Once logged in, locate and select the Content Scanner option from the sidebar. This will take you to the dashboard where you can manage all scanning jobs. 2. **Create a New Job** To create a new content scanning job, click the + New Scheduled Job button located at the top-right corner of the page. This will open a pop-up window where you can input all the necessary details to configure your job. 3. **Fill in Job Details**. Under the section: 1. Name: Enter a descriptive name for the job (e.g., “AWS Blogs Compliance Scan”). 2. Source Type: Change the platform source to monitor (X, Instagram, etc). 3. Document Evaluation Type: Select the type of evaluation to be performed (e.g., Website, Document). 4. Max Pages: Specify the maximum number of pages to scan (e.g., 10). 5. Frequency: Set the job to run once, or schedule on a regular cadence (daily, weekly, monthly, quarterly). 6. Brand: Choose the relevant brand from the dropdown menu. 7. Crawl Site Maps: Toggle this option on if you want the scanner to crawl and include site maps. 8. Enable Translation: Toggle this option on if multilingual content needs translation during evaluation. 9. URLs: Enter specific URLs to be scanned, separated by commas. 4. **Configure Additional Attributes** (Optional) Scroll down to the Attributes section if you need to include custom metadata fields for the job. Click on the + Assign New Field button to add a field. Enter the field name (e.g., “Region” or “Compliance Category”) and its corresponding value. These custom attributes help categorize or filter results during the analysis process. 5. **Review and Save** Before finalizing the job, review all the entered details to ensure they are accurate and complete. Once you’ve confirmed everything, click the Proceed button to save the job and add it to the scheduled job list. The job will now appear in the Content Scanner dashboard, where you can monitor its progress and results. #### Note: * If you encounter any issues or have questions about managing monitoring jobs, please don't hesitate to contact our support team at . We're here to assist you throughout the process. # Third Party - Influencer and Affiliates Only available in certain Enterprise plans Protege AI provides advanced social media monitoring capabilities tailored to assist lawyers and legal teams in managing legal risks associated with social media content on X, LinkedIn (Company Pages), Instagram, and TikTok. This feature enables users to monitor proprietary social media accounts for compliance with regulations such as proper disclosures, claims accuracy, and trademark permissions. Additionally, it facilitates the monitoring of sponsored influencers and ensures compliance with FTC social media advertising disclosure guidelines. The AI policies governing social media monitoring can be configured similarly to document review, allowing for customizable monitoring based on specific legal requirements. **Key Features:** 1. **Compliance Monitoring:** * Ensure compliance with regulatory requirements related to disclosures, claims accuracy, and trademark permissions across sponsored influencers social media accounts and affiliated pages * Configure AI policies to detect and flag potential compliance issues, allowing legal teams to address them proactively. 2. **Influencer Tracking:** * Track sponsored influencers associated with your company's social media activities. * Monitor influencer content for adherence to advertising disclosure guidelines set forth by regulatory bodies like the FTC. 3. **Customizable Policies:** * Tailor monitoring policies to address specific legal concerns and compliance requirements in all forms of content: text posts, video, and audio. * Configure AI policies to identify keywords, phrases, or patterns indicative of non-compliance or legal risks. **How to Set Up a Monitoring Job** 1. Navigate to the Monitoring Page. Go to the Influencer Monitoring section in the dashboard and click on Settings to view your policies and current jobs. 2. Create a New Job. Click the + Add Job button to open the “Create a Scheduled Job” interface. 3. Job Configuration: 1. Name: Enter a descriptive name for the job (e.g., “BrandX-IG Monitoring”). 2. Source Type: Select the platform to monitor (e.g., Instagram). 3. Document Evaluation Type: Choose the type of policy to apply (e.g., Brand Association). 4. Max Pages: Define the number of pages/posts to scan per job (e.g., 10). 5. Frequency: Select how often the job should run (Once, Daily, Weekly, etc.). 6. Account Username: Input the username of the influencer or affiliate to monitor. 7. Brand: Assign the relevant brand or campaign. 8. Save Feedback in Decision Store?: Toggle this on if you want to store evaluation results for future reference. 9. Enable Translation?: Turn this on to monitor posts in multiple languages.
4. Add Custom Attributes (Optional). Use the Attributes section to add custom fields (e.g., hashtags, keywords, or other metadata). 5. Review and Save. Click Proceed to save the job and activate monitoring. # Remediation Queue The Remediation Queue consolidates all flagged content from your content scanning jobs into a single, easy-to-navigate dashboard. It enables users to quickly review non-compliant posts, assign remediation tasks, and track resolution progress. With built-in tools to categorize issues and provide feedback, the queue ensures an organized approach to compliance management. Additionally, integration with the Protege AI platform allows for seamless updates and real-time tracking of remediation efforts, keeping stakeholders informed at every step. For setup, follow the instructions in [Task Manager Setup](/review/getting-started/task-manager-setup). # Translation Support Protege AI supports multi-language document scanning and translation capabilities, enabling you to review and analyze content in languages other than English. This feature is particularly valuable for organizations operating across multiple regions or reviewing international marketing materials. ## Overview The translation feature allows you to: * Scan and analyze documents written in various languages * Automatically translate content to English for policy review * Apply policy checks to translated content * Review original and translated versions side-by-side ## Supported Languages Protege AI supports translation for major world languages, including but not limited to: * Spanish * French * German * Italian * Portuguese * Japanese * Chinese (Simplified and Traditional) * Korean * Arabic * And many more For a complete list of supported languages, contact our support team. ## How Translation Works 1. **Document Detection**: When a document is scanned, Protege AI automatically detects the language 2. **Translation**: Non-English content is translated to English using advanced AI models 3. **Policy Application**: Policies and compliance checks are applied to the translated content 4. **Review**: Reviewers can view both the original and translated versions 5. **Feedback**: Policy feedback references both languages for context ## Using Translation in Scanner Jobs ### For Content Scanning Jobs When creating or editing a content scanning job: 1. Navigate to **Content Scanner** in the dashboard 2. Create a new job or edit an existing one 3. In the job configuration, translation is automatically enabled for detected non-English content 4. Policy checks will be applied to the translated version 5. Results will show both original and translated content ### For Document Reviews Translation is also available for individual document reviews: 1. Upload or scan a document in any supported language 2. Protege AI will detect the language and offer translation 3. Review the translated content with standard policy checks 4. Provide feedback referencing both original and translated text ## Translation Accuracy * Translation uses state-of-the-art AI models for high accuracy * Legal and marketing terminology is handled with specialized context * Complex sentences and idioms are translated to preserve meaning * For critical compliance work, human review of translations is recommended ## Best Practices * **Review Original Content**: Always reference the original language version when making final compliance decisions * **Cultural Context**: Be aware that some marketing claims or language may have different implications across cultures * **Custom Terminology**: Contact support to add industry-specific terminology to improve translation accuracy * **Disclosure Requirements**: Ensure translated disclosures maintain legal accuracy and completeness ## Enabling Translation Translation support is automatically enabled for all scanner jobs and document reviews. No additional configuration is required. For questions about translation capabilities or to request support for additional languages, contact . # Automated Actions When a content scanning job is completed, Protege AI can automatically create remediation tickets in your task management system based on risk thresholds. This streamlines the process of addressing compliance issues found during web content monitoring. ## Overview Automated actions for content scanning eliminate the manual step of creating tickets for policy violations. When a scan identifies issues that exceed your defined risk thresholds, change request tickets are automatically created with detailed information about the violations. ## How It Works 1. **Scan Completion**: A scheduled or one-time content scanning job finishes 2. **Risk Evaluation**: The entire report is evaluated against your configured risk thresholds 3. **Threshold Check**: If the aggregate risk score exceeds any defined threshold, an action is triggered 4. **Ticket Creation**: A change request ticket is automatically created in your task management system 5. **Details Included**: The ticket contains links to the scan report, specific violations, and affected pages ## Key Features ### Customizable Task Manager Integration You can specify which project in your task management system should receive the change request tickets, ensuring seamless integration with your existing workflow. ### Individual Risk Thresholds Each scanning job can have its own unique risk thresholds, allowing for tailored risk assessment based on: * Content type (proprietary vs. third-party) * Brand sensitivity * Platform (social media vs. website) * Compliance requirements ### Aggregate Risk Scoring Actions are triggered based on the combined risk across all scanned pages, not individual violations. This prevents ticket overload while ensuring significant issues are escalated. ## Configuration ### Setting Up Automated Actions for Scanner Jobs 1. Navigate to **Content Scanner** in the dashboard 2. Create a new job or edit an existing scheduled job 3. Go to the **Actions** tab 4. Select a project to create tickets in from your connected task manager 5. Configure risk levels and occurrence counts: * **High Risk**: Number of high-risk violations that trigger action * **Medium Risk**: Number of medium-risk violations that trigger action * **Low Risk**: Number of low-risk violations that trigger action 6. Press **Proceed** to save your configuration ### Threshold Examples **Conservative (High Sensitivity):** * Create ticket if: ≥1 High risk, ≥3 Medium risk, ≥10 Low risk **Moderate:** * Create ticket if: ≥2 High risk, ≥5 Medium risk, ≥20 Low risk **Lenient:** * Create ticket if: ≥3 High risk, ≥10 Medium risk, ≥50 Low risk ## Ticket Contents Automatically created tickets include: * **Scan Report Link**: Direct link to the full Protege scan report * **Summary**: Overview of violations found * **Risk Breakdown**: Count of High, Medium, and Low risk issues * **Affected Pages**: List of URLs with violations * **Policy Types**: Categories of policies violated * **Timestamps**: When the scan was completed * **Brand Information**: Which brand(s) were affected ## Supported Task Managers Automated actions for content scanning work with: * Asana * Jira * Smartsheets * Wrike ## Best Practices * **Job-Specific Thresholds**: Use stricter thresholds for high-visibility content (homepage, landing pages) * **Platform Considerations**: Social media may require more lenient thresholds due to user-generated content * **Regular Adjustment**: Review and adjust thresholds based on your team's capacity and priorities * **Brand Differentiation**: Apply different thresholds for different brands based on risk tolerance * **Test First**: Run initial scans without actions enabled to calibrate appropriate thresholds ## Action History Track all automated ticket creation: 1. Go to **Settings** → **Action History** 2. Filter by "Content Scanner" actions 3. Review which scans triggered automatic ticket creation 4. Analyze patterns to optimize thresholds ## Managing Created Tickets Tickets created by automated actions can be: * Assigned to specific team members * Prioritized based on risk levels * Tracked through your normal workflow * Closed when issues are remediated * Referenced for compliance audits ## Disabling Actions To disable automated actions for a specific scanner job: 1. Edit the scanner job 2. Navigate to the **Actions** tab 3. Remove the project selection or adjust thresholds to prevent triggering 4. Save your changes ## Integration Notes * Actions respect your task manager's project permissions * Tickets are created under the Protege integration user * Custom fields in your task manager can be populated (contact support) * Ticket templates can be customized for your organization For questions about configuring automated actions for content scanning, contact . # Overview Protege Review includes powerful enterprise-grade features designed for organizations that need advanced user management, compliance capabilities, and AI-powered assistance across their entire environment. ## Overview Enterprise Features include: * **Assistant**: AI-powered query and insights across all your Protege data * **Integrations & API**: Enterprise access to document review APIs, reference data, and implementation support * **User Management**: Granular role-based access control and user administration * **Enterprise SSO**: Single sign-on integration with major identity providers * **Archiving & Compliance**: Regulatory compliance archiving for SEC, FINRA, and FTC requirements ## Access and Setup Enterprise features are available to all users in your organization. Some features may require additional configuration or approval from your account administrator. For questions about enterprise features or to enable specific capabilities, contact our support team at . # Assistant ShieldLlama Assistant is Protege's enterprise copilot for searching, analyzing, and synthesizing information across your compliance environment. It is designed to help legal, compliance, brand, and operations teams move faster without switching across multiple systems. Assistant can answer questions using the data already available in your Protege workspace, including document reviews, monitoring results, policies, claims, and related workflow context. Use the pages in this section to understand: * common enterprise use cases * what data the assistant can access * how to frame questions for better results For customers evaluating deeper workflow automation or external agent integrations, see the enterprise [Integrations & API](/review/enterprise-features/integrations-and-api) guide. # Use Cases Assistant is in Public Beta for Enterprise plans. #### **What the Assistant Can Do** ShieldLlama Assistant by Protege AI is an intelligent copilot that provides comprehensive data access and analysis capabilities for all your data in Protege. Assistant is integrated with all of our other modules, such as Review AI, Digital Asset Manager, Complaint Monitor, Web Monitor. ### Can you show me some examples? 🏷️ **Need to check if your new product claim is compliant?** "Analyze this marketing document for potential FDA violations and compare it to our previously approved content." 📊 **Want to see trends across all your brands?** "Generate a brand compliance report showing unresolved policy violations and acknowledgment status for the last quarter." 🔍 **Looking for similar claims that were flagged before?** "Find all documents with similar performance claims that have been flagged for FTC compliance issues." ### Do you have some tips for my use case? **Be Specific with Your Questions** Instead of "Check compliance," try "What is the public compliance risk for Acme Brand" or "Find similar trademark usage issues from the last 6 months." **Use Brand Context** Specify which brand you're working with: "Show me Unqualified Claims violations for Acme Brand" gives more targeted results than general compliance queries. **Leverage Document Context** When reviewing a specific document, ask targeted questions about that content rather than general compliance queries. ### Document Review Mode When you open a document for review, ShieldLlama automatically loads the full context including brand information, compliance history, and related tasks. You can then ask specific questions about that document. **What's loaded in Document Review Mode?** * Document title, type, and current status * Associated brand and evaluation requirements * Author information and publication dates * Linked compliance tasks and deadlines * Previous compliance feedback and history * Full content including text, images, and video analysis ### Can you show me some Document Review examples? 📄 **Marketing Material Analysis** "What specific product claims does this brochure make, and are any similar to previously flagged content?" ⚖️ **Risk Assessment** "Identify any potential FTC violations in this social media campaign and suggest safer alternatives." 🔗 **Cross-Reference Check** "Compare the claims in this document to our competitor analysis - are we making any unsupported comparisons?" 📋 **Compliance Status** "What's the current compliance status of this document and what tasks are still pending review?" # Available Data ### What ShieldLlama Assistant can access: **Your Complete Compliance Database** * All policy violations and their resolution status * Claims database with risk assessments * Trademark monitoring and infringement alerts * Historical compliance trends and patterns **Document Repository** * Full-text search across all marketing materials * OCR results from images and video content * Document versioning and approval workflows * Cross-brand content comparison **Integration Data** * Task management systems (Asana, Jira, etc.) * Content scanning results from websites and social media * User activity and acknowledgment tracking * Brand-specific policy configurations ### Important: What ShieldLlama Assistant cannot do ShieldLlama is a **research and analysis tool** that helps prepare information for legal review. It cannot yet support: * Editing data in Protege, such as modify policies, changing scanning jobs, or uploading new docs for review. Think of ShieldLlama as your smart research assistant that helps legal teams work more efficiently by organizing information and identifying potential issues. ### # Integrations & API Protege offers enterprise integration options for teams that want to connect document review and compliance workflows to their own systems, automations, or agent frameworks. ## What Is Available * **External Review API**: Submit text and file-based document reviews, poll asynchronous jobs, and retrieve structured review findings. * **Reference Data Access**: Discover tenant-scoped brands, policies, policy groups, and document evaluation types required to drive integrations. * **Monitoring Workflows**: Manage scanner jobs and retrieve report data for ongoing web and content monitoring use cases. * **Implementation Support**: Enterprise customers can receive sandbox access, sample requests, and enablement support during setup. ## Where Agent Skills Fit An agent skill can be a useful accelerator, but it is usually **not** the primary enterprise artifact. Agent skills work best when a client already has an agent platform and wants a lightweight wrapper that gives their agents fast access to Protege review workflows. In that setup, the skill acts as a convenience layer over the Protege API. For most enterprise evaluations, the stronger primary deliverable is: 1. clear API documentation 2. a tested sandbox workflow 3. sample requests or a starter client 4. a concise business-case narrative showing why Protege outperforms a DIY reviewer Then, if the client is actively standardizing on an agent platform, add an agent skill as an optional starter artifact rather than the core integration surface. ## Recommended Enterprise Package For customer onboarding or benchmark exercises, we recommend sharing: * **Business case overview** explaining why Protege is broader than a point document reviewer * **API and sandbox guide** for technical validation * **Example review workflow** showing file upload, async polling, and findings retrieval * **Optional agent skill** for teams that want to expose Protege to their internal agents quickly ## Access and Enablement If you need an API key, help selecting a `documentEvaluationTypeId`, or sample requests for your environment, contact the Protege team through your shared enterprise support channel or email . The detailed endpoint reference for document reviews remains available in the Document Review section: {% content-ref url="/pages/wH4eclB0efC3ka5ulg6i" %} [API Reference](/review/getting-started/api-reference) {% endcontent-ref %} # Managing Users Easily manage your team’s access and permissions with Protege AI’s User Management system. This page allows admins to add new users, assign roles, and customize permissions to align with your organization’s workflow. Whether you’re onboarding new team members or adjusting access levels, the intuitive interface ensures seamless collaboration while maintaining strict control over sensitive data. {% content-ref url="/pages/9GKWWF0l8i0bMpBzlCFi" %} [User Roles & Permissions](/review/enterprise-features/managing-users/user-roles-and-permissions) {% endcontent-ref %} {% content-ref url="/pages/z25FggPpDBIEmKDp6HOX" %} [User Management](/review/enterprise-features/managing-users/user-management) {% endcontent-ref %} # User Roles & Permissions This page allows administrators to manage and customize user roles and permissions in Protege AI. Easily create new roles, assign permissions to match specific job functions, and update access settings for existing users. With a clear, intuitive interface, this tool ensures secure and efficient collaboration by giving team members the precise access they need to perform their tasks effectively. {% tabs %} {% tab title="Assigning Roles" %} 1. **Log in to the Protege Dashboard.** Navigate to the [Protege AI platform](https://app.tryprotege.com) and log in using your admin credentials. 2. **Access User Management.** Click on the Settings menu from the sidebar. Select Users to view the user management page. 3. **Open Role Permissions.** Click Edit Access, and modify the permission matrix. Press save when completed. {% endtab %} {% tab title="Editing Role Access" %} 1. **Log in to the Protege Dashboard.** Navigate to the [Protege AI platform](https://app.tryprotege.com) and log in using your admin credentials. 2. **Access User Management.** Click on the Settings menu from the sidebar. Select Users to view the user management page. 3. **Adjust Role Permissions.** Review the permission matrix displayed in the pop-up window. Enable or disable specific permissions by toggling the checkmarks for each feature (e.g., Approve Claim, Content Scanner, etc.).
4. **Verify and Save.** Ensure that the selected permissions align with the user’s responsibilities. Once all necessary adjustments have been made, click Save to apply the changes. {% endtab %} {% tab title="Add New Roles" %} 1. **Log in to the Protege Dashboard.** Navigate to the [Protege AI platform](https://app.tryprotege.com) and log in using your admin credentials. 2. **Access User Management.** Click on the Settings menu in the sidebar, then select Users. 3. **Create a New Role.** Click Edit Access, then select + New Role at the top of the window. 4. **Name the Role.** Enter a clear, descriptive name (e.g., “Compliance Specialist” or “Marketing Reviewer”). 5. **Assign Permissions.** Toggle the checkboxes to enable the appropriate permissions for the role. 6. **Save the Role.** Click Save to create the role. 7. **Assign the Role to Users.** Return to the Users page, select a user, and choose the new role from the drop-down in their profile. {% endtab %} {% endtabs %} **Note**: * If you encounter any issues or have questions about managing users, please don't hesitate to contact our support team at . We're here to assist you throughout the process. # User Management In Protege AI, you have full control over managing users to ensure seamless collaboration and efficient content review processes. Below, we outline the steps to add and remove users from your account using the dashboard. {% tabs %} {% tab title="Add Users" %} 1. **Access the Dashboard**: Log in to your Protege AI account via the dashboard at [app.tryprotege.com](https://app.tryprotege.com). 2. **Navigate to Settings**: Once logged in, navigate to the "Settings" section of the dashboard. This is located at the bottom of the navigation sidebar. 3. **Access Users Page**: Within the Settings section, locate and click on the "Users" page. This is where you can manage the users associated with your account. 4. **Add a New User**: To add a new user, look for the option or button labeled "Invite User." Click on this option. 5. **Enter User Details**: In the pop-up, enter the email for the new user. 6. **Send Invitation**: Once you've entered the user's details, send the invitation. An email invitation will be sent to the specified email address, prompting the user to join your Protege AI workspace. 7. **Confirmation**: Upon accepting the invitation, the new user will be added to your account and granted access to the Protege AI platform. {% endtab %} {% tab title="Remove Users" %} 1. **Access the Dashboard**: Log in to your Protege account via the dashboard at [app.tryprotege.com](https://app.tryprotege.com). 2. **Navigate to Settings**: Once logged in, navigate to the "Settings" section of the dashboard. This is located at the bottom of the navigation sidebar. 3. **Locate User to Remove**: On the Users page, locate the user you wish to remove from your account. This may be done by searching or scrolling through the list of users. 4. **Initiate Removal**: Next to the user's email address, look for the button on the right-hand side. Click on this option to initiate the removal process. 5. **Confirmation**: Confirm the removal of the user from your account. Press confirm to finalize the action. 6. **User Removal**: Once confirmed, the user will be removed from your Protege workspace, revoking their access to the platform. {% endtab %} {% endtabs %} #### Note: * When adding users, you may be billed according to your contract to accommodate the new additions. * If you encounter any issues or have questions about managing users, please don't hesitate to contact our support team at . We're here to assist you throughout the process. --- [Next Page](/llms-full.txt/1)