Documentation Index Fetch the complete documentation index at: https://docs.agentic.scope3.com/llms.txt
Use this file to discover all available pages before exploring further.
v1 is deprecated. August 1, 2026 is the final day these endpoints will be available. Migrate to v2 , which is the current stable API.
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:
X-API-Key: your-secret-key
Bearer Token (OAuth)
For OAuth-based authentication:
Authorization: Bearer jwt-token
Basic Auth
Username/password authentication:
Authorization: Basic base64(username:password)
Base URL
Your outcome agent server runs at your own domain:
https://outcome-agent.yourcompany.com
This is the URL you provide when registering with Scope3.
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.
Node.js/Express
Python/Flask
app . post ( '/get-proposed-tactics' , async ( req , res ) => {
const { campaignId , budgetRange , channels , seatId } = req . body ;
// Analyze if we can handle this campaign
const canHandle = await analyzeCampaign ({ channels , budgetRange });
if ( ! canHandle ) {
return res . json ({ proposedTactics: [] });
}
// Propose tactics
res . json ({
proposedTactics: [
{
tacticId: "premium-vcpm-display" ,
execution: "Target premium inventory at $2.50 vCPM with 85% viewability" ,
budgetCapacity: 50000 ,
pricing: {
method: "vcpm" ,
rate: 2.50 ,
currency: "USD"
},
sku: "premium-vcpm" ,
customFieldsRequired: [
{
fieldName: "targetVCPM" ,
fieldType: "number" ,
description: "Target vCPM in USD"
}
]
}
]
});
});
Request Body (from Scope3)
Field Type Description campaignIdstring Campaign ID budgetRangeobject Budget range (buyer won’t reveal full budget) budgetRange.minnumber Minimum budget budgetRange.maxnumber Maximum budget budgetRange.currencystring Currency (ISO 4217 code, defaults to USD) startDatestring Campaign start date in UTC (ISO 8601) endDatestring Campaign end date in UTC (ISO 8601) channelsarray Channels: display, video, audio, native, ctv (ADCP aligned) countriesarray ISO 3166-1 alpha-2 country codes objectivesarray Campaign objectives/outcomes briefstring Campaign brief text acceptedPricingMethodsarray Pricing methods buyer accepts: cpm, vcpm, cpc, cpa, cpv, flat_fee, revshare promotedOfferingsarray Specific offerings buyer is interested in seatIdstring Seat/account ID
Your Response
Field Type Required Description proposedTacticsarray Yes List of tactics you can handle proposedTactics[].tacticIdstring Yes Unique ID (you generate this) proposedTactics[].executionstring Yes How you’ll execute this tactic proposedTactics[].budgetCapacitynumber Yes Max budget you can handle proposedTactics[].pricingobject Yes Your pricing model proposedTactics[].pricing.methodstring Yes Pricing method: cpm, vcpm, cpc, cpa, cpv, flat_fee, revshare proposedTactics[].pricing.ratenumber Yes Rate (e.g., CPM in USD, percentage for revshare) proposedTactics[].pricing.currencystring No Currency (ISO 4217 code, defaults to USD) proposedTactics[].skustring No Identifier for this tactic type proposedTactics[].customFieldsRequiredarray 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.
Node.js/Express
Python/Flask
app . post ( '/accept-proposal' , async ( req , res ) => {
const { tacticId , proposalId , tacticContext , customFields , proposal_context } = req . body ;
try :
// Set up tactic management
await setupTactic ( tacticId , proposalId , tacticContext , customFields , proposal_context );
// Acknowledge
res . json ({ acknowledged: true });
// Start optimization (async)
optimizeTactic ( tacticId ). catch ( console . error );
} catch ( error ) {
res.json({
acknowledged : false ,
reason : error . message
});
}
});
Request Body (from Scope3)
Field Type Description tacticIdstring ID of the tactic from the strategy table (assigned when user accepts your proposal) proposalIdstring ID of the proposal that was accepted (matches proposalId from your response) tacticContextobject Complete tactic details tacticContext.budgetnumber Budget allocated tacticContext.budgetCurrencystring Currency (ISO 4217 code, defaults to USD) tacticContext.startDatestring Campaign start date in UTC (ISO 8601) tacticContext.endDatestring Campaign end date in UTC (ISO 8601) tacticContext.channelstring Advertising channel tacticContext.countriesarray Target countries tacticContext.creativesarray Creative assets tacticContext.brandStandardsobject Brand safety rules (Scope3 handles) brandAgentIdstring Brand agent ID seatIdstring Seat/account ID customFieldsobject Custom fields from advertiser proposal_contextobject The proposal_context data you returned in your original proposal response
Your Response
Field Type Required Description acknowledgedboolean Yes true to accept, false to declinereasonstring 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.
Node.js/Express
Python/Flask
app . post ( '/tactic-context-updated' , async ( req , res ) => {
const { tacticId , tactic , patch } = req . body ;
// Update tactic configuration based on changes
await updateTacticConfig ( tacticId , patch );
res . status ( 200 ). send ();
});
Request Body (from Scope3)
Field Type Description tacticIdstring Tactic ID tacticobject Current tactic state (after changes) patcharray JSON Patch (RFC 6902) changes
Patch Format Example
[
{
"op" : "replace" ,
"path" : "/budget" ,
"value" : 60000
}
]
Your Response
Return 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.
app . post ( '/tactic-creatives-updated' , async ( req , res ) => {
const { tacticId , tactic , patch } = req . body ;
// Update creatives in media buys
await updateCreatives ( tacticId , patch );
res . status ( 200 ). send ();
});
Request Body (from Scope3)
Field Type Description tacticIdstring Tactic ID tacticobject Current tactic with updated creatives patcharray JSON Patch changes to creatives
Your Response
Return 200 OK.
POST /tactic-feedback
Called by Scope3 when : Sending performance feedback
Your agent MAY use this to optimize delivery.
app . post ( '/tactic-feedback' , async ( req , res ) => {
const { tacticId , deliveryIndex , performanceIndex } = req . body ;
// Optimize based on feedback
if ( deliveryIndex < 90 ) {
await increaseBudgetAllocation ( tacticId );
}
if ( performanceIndex > 120 ) {
await scaleWinningProducts ( tacticId );
}
res . status ( 200 ). send ();
});
Request Body (from Scope3)
Field Type Description tacticIdstring Tactic ID startDatestring Feedback interval start in UTC (ISO 8601) endDatestring Feedback interval end in UTC (ISO 8601) deliveryIndexnumber 100 = on target, <100 = under-delivering, >100 = over-delivering performanceIndexnumber 100 = maximum, relative to target or other tactics
Your Response
Return 200 OK.
Once managing a tactic, your agent calls Scope3’s platform APIs to execute media buys.
Get Sales Agent Products
curl https://api.agentic.scope3.com/rest/v1/get-products \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"channels": ["display"],
"countries": ["US"]
}'
curl https://api.agentic.scope3.com/rest/v1/create-media-buy \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"tacticId": "premium-vcpm-display",
"productId": "prod_456",
"budget": 10000
}'
Update Tactic Targeting
curl https://api.agentic.scope3.com/rest/v1/update-targeting \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"tacticId": "premium-vcpm-display",
"segments": ["premium-auto-enthusiasts"],
"frequencyCap": {
"impressions": 5,
"period": "day"
}
}'
See the main API Reference for complete documentation of Scope3’s platform APIs.
Registering Your Outcome Agent
Once your server is running, register with Scope3:
curl -X POST https://api.agentic.scope3.com/rest/v1/outcome-agent-register \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "vCPM Optimizer Pro",
"description": "Optimizes for lowest vCPM with high viewability",
"endpointUrl": "https://media-agent.yourcompany.com",
"authenticationType": "API_KEY",
"apiKey": "your-secret-key-for-scope3-to-use",
"supportedChannels": ["display", "video"],
"supportedCountries": ["US", "CA", "GB"]
}'
Registration Fields
Field Type Required Description namestring Yes Display name for your agent descriptionstring Yes What your agent does endpointUrlstring Yes Base URL of your server authenticationTypestring Yes API_KEY, BEARER_TOKEN, or BASIC_AUTHapiKeystring Conditional Required if using API_KEY auth bearerTokenstring Conditional Required if using BEARER_TOKEN auth username / passwordstring Conditional Required if using BASIC_AUTH supportedChannelsarray Yes Channels you support supportedCountriesarray 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 200 with acknowledged: false to decline tactics gracefully
Provide clear error messages in reason field
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
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
Contact your Scope3 account manager for staging access.
Support