MadHive contextual segments API
The contextual segments API from MadHive — 1 operation(s) for contextual segments.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/madhive-contextual-segments-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Madhive contextual segments API
version: 1.0.0
description: "The Madhive API provides a comprehensive interface for digital advertising clients and services.\n\n## Authentication\nThis API uses OAuth 2.0 client credentials flow for authentication. To access protected endpoints:\n\n1. **Obtain an access token** using the `/oauth/token` endpoint with your client credentials\n2. **Include the token** in subsequent API requests using the `Authorization` header:\n ```\n Authorization: Bearer YOUR_ACCESS_TOKEN_HERE\n ```\n\n### Token Usage Example\n```bash\n# Get access token\ncurl -X POST \"https://api2.madhive.com/oauth/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET\"\n\n# Use token in API requests\ncurl -H \"Authorization: Bearer YOUR_ACCESS_TOKEN_HERE\" \\\n \"https://api2.madhive.com/v1/campaigns\"\n```\n\n**Note:** Access tokens have an expiration time. You should handle token refresh in your application logic.\n"
servers:
- url: https://api2.madhive.com/api
description: apigee
tags:
- name: contextual segments
paths:
/v1/contextual-segments:
get:
tags:
- contextual segments
summary: List available contextual segments for targeting and avoidance
description: Returns the list of contextual segments (IAS) available for use in line item contextual targeting and avoidance. Segments can be filtered by type (TARGETING or AVOIDANCE).
operationId: getContextualSegments
parameters:
- $ref: '#/components/parameters/X-Cloud-Trace-Context'
- in: query
name: type
schema:
type: string
enum:
- TARGETING
- AVOIDANCE
description: Filter segments by type (TARGETING or AVOIDANCE). If omitted, returns all contextual segments.
example: TARGETING
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ContextualSegmentListResponse'
examples:
response:
value:
segments:
- id: '3005009'
name: Automotive - Family Car
category: CONTEXTUAL
type: TARGETING
- id: '3005010'
name: News & Politics
category: CONTEXTUAL
type: TARGETING
- id: '1500080'
name: Adult Content
category: CONTEXTUAL
type: AVOIDANCE
transaction:
id: 4af459ff8e1a36b6bb74fb88f1a02477
created: '2026-06-02T15:04:00Z'
'401':
$ref: '#/components/responses/401Unauthorized'
security:
- oauth2: []
components:
parameters:
X-Cloud-Trace-Context:
name: X-Cloud-Trace-Context
in: header
description: gcp trace
required: false
schema:
type: string
default: 91f9f012dc7c7ffc13604c77f12a8931
responses:
401Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
$ref: '#/components/examples/401Ex'
schemas:
ContextualSegmentListResponse:
type: object
x-isnullable: false
required:
- segments
- transaction
properties:
segments:
type: array
items:
$ref: '#/components/schemas/ExternalSegment'
description: list of contextual segments
transaction:
$ref: '#/components/schemas/Transaction'
Transaction:
type: object
x-go-type-skip-optional-pointer: true
x-omitempty: false
required:
- id
- taskId
- created
properties:
id:
type: string
description: trace id
example: 4af459ff8e1a36b6bb74fb88f1a02477
taskId:
type: string
x-omitempty: true
description: task id
example: '14158884487309867565'
created:
type: string
description: 'order created date, format: yyyy-mm-dd hh:mm:ss'
example: '2030-11-02T15:04:00Z'
ErrorResponse:
type: object
required:
- transaction
properties:
errors:
type: array
x-go-type-skip-optional-pointer: true
items:
type: string
description: many error messages
error:
type: string
x-go-type-skip-optional-pointer: true
description: error message
example: Unauthorized
status:
type: string
x-go-type-skip-optional-pointer: true
description: status of the service
example: ERROR
transaction:
$ref: '#/components/schemas/Transaction'
ExternalSegment:
type: object
x-isnullable: false
required:
- id
- name
- category
- type
properties:
id:
type: string
x-isnullable: false
description: external segment ID (IAS segment identifier)
example: '3005009'
name:
type: string
x-isnullable: false
description: segment name
example: Automotive - Family Car
category:
type: string
enum:
- CONTEXTUAL
- KEYWORD
x-isnullable: false
description: segment category
example: CONTEXTUAL
type:
type: string
enum:
- TARGETING
- AVOIDANCE
x-isnullable: false
description: segment type (targeting or avoidance)
example: TARGETING
examples:
401Ex:
value:
error: unauthorized
status: ERROR
transaction:
id: 4af459ff8e1a36b6bb74fb88f1a02477
taskId: '14158884487309867565'
created: '2030-11-02T15:04:00Z'
securitySchemes:
oauth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api2.madhive.com/oauth/token
scopes: {}
basicAuth:
type: http
description: Basic Authentication Not Implemented
scheme: basic
bearerAuth:
type: apiKey
name: Authorization
in: header
description: jwt access token for authentication