Overview
This reference describes the protocol your outcome agent server must implement. These are endpoints that YOU implement on YOUR infrastructure, and Scope3’s platform will call them.Download OpenAPI Spec
Download the complete OpenAPI specification for the Outcome Agent Protocol
Authentication
Your outcome agent server must authenticate requests from Scope3. When registering your agent, specify which authentication type you support:API Key (Recommended)
Scope3 sends requests with an API key in the header:Bearer Token (OAuth)
For OAuth-based authentication:Basic Auth
Username/password authentication:Base URL
Your outcome agent server runs at your own domain:Endpoints You Must Implement
POST /get-proposed-tactics
Called by Scope3 when: Setting up a new campaign Scope3 calls this to ask what tactics your agent can handle. Analyze the campaign and respond with proposed tactics, budget capacity, and pricing.| Field | Type | Description |
|---|---|---|
campaignId | string | Campaign ID |
budgetRange | object | Budget range (buyer won’t reveal full budget) |
budgetRange.min | number | Minimum budget |
budgetRange.max | number | Maximum budget |
budgetRange.currency | string | Currency (ISO 4217 code, defaults to USD) |
startDate | string | Campaign start date in UTC (ISO 8601) |
endDate | string | Campaign end date in UTC (ISO 8601) |
channels | array | Channels: display, video, audio, native, ctv (ADCP aligned) |
countries | array | ISO 3166-1 alpha-2 country codes |
objectives | array | Campaign objectives/outcomes |
brief | string | Campaign brief text |
acceptedPricingMethods | array | Pricing methods buyer accepts: cpm, vcpm, cpc, cpa, cpv, flat_fee, revshare |
promotedOfferings | array | Specific offerings buyer is interested in |
seatId | string | Seat/account ID |
| Field | Type | Required | Description |
|---|---|---|---|
proposedTactics | array | Yes | List of tactics you can handle |
proposedTactics[].tacticId | string | Yes | Unique ID (you generate this) |
proposedTactics[].execution | string | Yes | How you’ll execute this tactic |
proposedTactics[].budgetCapacity | number | Yes | Max budget you can handle |
proposedTactics[].pricing | object | Yes | Your pricing model |
proposedTactics[].pricing.method | string | Yes | Pricing method: cpm, vcpm, cpc, cpa, cpv, flat_fee, revshare |
proposedTactics[].pricing.rate | number | Yes | Rate (e.g., CPM in USD, percentage for revshare) |
proposedTactics[].pricing.currency | string | No | Currency (ISO 4217 code, defaults to USD) |
proposedTactics[].sku | string | No | Identifier for this tactic type |
proposedTactics[].customFieldsRequired | array | No | Custom fields needed from advertiser |
POST /accept-proposal
Called by Scope3 when: Your proposal is accepted and you are assigned to manage a tactic Your agent should acknowledge and begin managing the tactic, or decline if unable to fulfill.| Field | Type | Description |
|---|---|---|
tacticId | string | ID of the tactic from the strategy table (assigned when user accepts your proposal) |
proposalId | string | ID of the proposal that was accepted (matches proposalId from your response) |
tacticContext | object | Complete tactic details |
tacticContext.budget | number | Budget allocated |
tacticContext.budgetCurrency | string | Currency (ISO 4217 code, defaults to USD) |
tacticContext.startDate | string | Campaign start date in UTC (ISO 8601) |
tacticContext.endDate | string | Campaign end date in UTC (ISO 8601) |
tacticContext.channel | string | Advertising channel |
tacticContext.countries | array | Target countries |
tacticContext.creatives | array | Creative assets |
tacticContext.brandStandards | object | Brand safety rules (Scope3 handles) |
brandAgentId | string | Brand agent ID |
seatId | string | Seat/account ID |
customFields | object | Custom fields from advertiser |
proposal_context | object | The proposal_context data you returned in your original proposal response |
| Field | Type | Required | Description |
|---|---|---|---|
acknowledged | boolean | Yes | true to accept, false to decline |
reason | string | No | Reason if declining |
POST /tactic-context-updated
Called by Scope3 when: Tactic is modified (budget, schedule, etc.) Your agent MUST handle these changes as they may impact delivery.| Field | Type | Description |
|---|---|---|
tacticId | string | Tactic ID |
tactic | object | Current tactic state (after changes) |
patch | array | JSON Patch (RFC 6902) changes |
200 OK to acknowledge.
POST /tactic-creatives-updated
Called by Scope3 when: Creatives are added, removed, or modified Update your media buys to use the new creative assets.| Field | Type | Description |
|---|---|---|
tacticId | string | Tactic ID |
tactic | object | Current tactic with updated creatives |
patch | array | JSON Patch changes to creatives |
200 OK.
POST /tactic-feedback
Called by Scope3 when: Sending performance feedback Your agent MAY use this to optimize delivery.| Field | Type | Description |
|---|---|---|
tacticId | string | Tactic ID |
startDate | string | Feedback interval start in UTC (ISO 8601) |
endDate | string | Feedback interval end in UTC (ISO 8601) |
deliveryIndex | number | 100 = on target, <100 = under-delivering, >100 = over-delivering |
performanceIndex | number | 100 = maximum, relative to target or other tactics |
200 OK.
Using Scope3’s Platform APIs
Once managing a tactic, your agent calls Scope3’s platform APIs to execute media buys.Get Sales Agent Products
Create Media Buy
Update Tactic Targeting
Registering Your Outcome Agent
Once your server is running, register with Scope3:| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name for your agent |
description | string | Yes | What your agent does |
endpointUrl | string | Yes | Base URL of your server |
authenticationType | string | Yes | API_KEY, BEARER_TOKEN, or BASIC_AUTH |
apiKey | string | Conditional | Required if using API_KEY auth |
bearerToken | string | Conditional | Required if using BEARER_TOKEN auth |
username / password | string | Conditional | Required if using BASIC_AUTH |
supportedChannels | array | Yes | Channels you support |
supportedCountries | array | Yes | Countries you support |
Best Practices
Endpoint Reliability
- Respond within 10 seconds
- Use proper HTTP status codes (200, 400, 500)
- Implement idempotency for all operations
- Log all requests for debugging
Error Handling
- Return
200withacknowledged: falseto decline tactics gracefully - Provide clear error messages in
reasonfield - Don’t return 5xx errors for business logic failures
Security
- Validate authentication on all requests
- Use HTTPS only
- Rotate API keys regularly
- Rate limit to prevent abuse
Performance
- Process requests asynchronously when possible
- Use background jobs for optimization
- Cache frequently accessed data
- Monitor endpoint latency
Testing Your Implementation
Use Scope3’s staging environment to test your outcome agent:- Register with staging:
https://api.agentic.staging.scope3.com - Test each endpoint with sample payloads
- Verify authentication works correctly
- Monitor logs for errors
- Validate responses match the protocol spec
Support
- Protocol Questions: [email protected]
- OpenAPI Spec: Download outcome-agent-openapi.yaml
- Platform APIs: See API Reference
- Partnership Inquiries: [email protected]