# API documentation

## Retrieve targeting lists for a given URL

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/communities/:communityId/contextual/semantic_extraction`

#### Path Parameters

| Name                                          | Type    | Description                              |
| --------------------------------------------- | ------- | ---------------------------------------- |
| communityId<mark style="color:red;">\*</mark> | integer | The ID of your community or organisation |

#### Request Body

| Name                                          | Type   | Description                                                                  |
| --------------------------------------------- | ------ | ---------------------------------------------------------------------------- |
| url<mark style="color:red;">\*</mark>         | string | The URL for which you want to retrieve the list of attached targeting lists. |
| channel\_id<mark style="color:red;">\*</mark> | string | The ID of the channel associated with the URL.                               |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status": "ok",
    "data": {
        "targeting_lists": [
            {
                "id": "123"
            },
            {
                "id": "456"
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

## Retrieve all targeting lists

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/organisations/:organisationId/contextual/targeting_lists`

#### Path Parameters

| Name                                             | Type    | Description                                                                   |
| ------------------------------------------------ | ------- | ----------------------------------------------------------------------------- |
| organisationId<mark style="color:red;">\*</mark> | integer | The ID of the organisation for which you want to retrieve the targeting lists |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status": "ok",
    "data": [
        {
            "type": "SEMANTIC",
            "id": "1",
            "organisation_id": "1",
            "status": "INIT",
            "live_activation_ts": null,
            "name": "Targeting_List_Name",
            "short_description": "",
            "token": "cardinal-ack",
            "url_count": 21860,
            "last_30_days_page_views": 8066996,
            "created_ts": 1692607279222,
            "created_by": "1",
            "last_modified_ts": null,
            "last_modified_by": null,
            "archived": false,
            "query_id": "1"
        }
    ],
    "count": 1,
    "total": 1,
    "first_result": 0,
    "max_results": 10
}
```

{% endtab %}
{% endtabs %}

## Retrieve targeting list basic information

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/organisations/:organisationId/contextual/targeting_lists/:targetingListId`

#### Path Parameters

| Name                                              | Type    | Description                              |
| ------------------------------------------------- | ------- | ---------------------------------------- |
| organisationId<mark style="color:red;">\*</mark>  | integer | The ID of the organisation               |
| targetingListId<mark style="color:red;">\*</mark> | Integer | The ID of the targeting list to retrieve |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status": "ok",
    "data": {
        "type": "SEMANTIC",    // SEMANTIC, PANEL_BASED
        "id": "1",
        "organisation_id": "1",
        "segment_id": "7105867",    // Only for PANEL_BASED type
        "volume_ratio": 0.8313403,    // Only for PANEL_BASED type
        "status": "INIT",
        "live_activation_ts": null,
        "last_lift_computation_ts": 1700100423716,    // Only for PANEL_BASED type
        "name": "Targeting_List_Name",
        "short_description": "",
        "token": "cardinal-ack",
        "url_count": 21860,
        "last_30_days_page_views": 8066996,
        "created_ts": 1692607279222,
        "created_by": "1",
        "last_modified_ts": null,
        "last_modified_by": null,
        "archived": false,
        "query_id": "1"    // Only for SEMANTIC type
    }
}
```

{% endtab %}
{% endtabs %}

## Retrieve semantic targeting list query

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/organisations/:organisationId/contextual/queries/:queryId`

#### Path Parameters

| Name                                             | Type    | Description                                                |
| ------------------------------------------------ | ------- | ---------------------------------------------------------- |
| organisationId<mark style="color:red;">\*</mark> | integer | The ID of the organisation                                 |
| queryId<mark style="color:red;">\*</mark>        | Integer | The ID of the query retrieved in a seamntic targeting list |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status": "ok",
    "data": {
        "id": "1",
        "organisation_id": "1",
        "query_data": {
            "language_name": "JSON_SEMANTIC",
            "language_version": "1",
            "query": {
                "include": {
                    "entity_ids": [
                        "1",
                        "2"
                    ],
                    "iab_category_ids": [
                        "1"
                    ]
                },
                "exclude": {
                    "entity_ids": [],
                    "channel_ids": [
                        "1",
                        "2",
                        "3",
                        "4",
                        "5"
                    ],
                    "iab_category_ids": []
                }
            }
        },
        "created_by": "1",
        "created_ts": 1692607279084,
        "last_modified_by": null,
        "last_modified_ts": null
    }
}
```

{% endtab %}
{% endtabs %}

## Retrieve IAB category information&#x20;

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/communities/:communityId/contextual/categories/:categoryId`

#### Path Parameters

| Name                                          | Type    | Description                            |
| --------------------------------------------- | ------- | -------------------------------------- |
| communityId<mark style="color:red;">\*</mark> | integer | The ID of the community                |
| categoryId<mark style="color:red;">\*</mark>  | Integer | The ID of the category to be retrieved |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status": "ok",
    "data": {
        "id": "25",
        "name": "News and Politics>Politics>War and Conflicts",
        "url_count": 13549,
        "last_30_days_page_views": 4914430
    }
}
```

{% endtab %}
{% endtabs %}

## Retrieve entity information&#x20;

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/communities/:communityId/contextual/entities/:entityId`

#### Path Parameters

| Name                                             | Type    | Description                          |
| ------------------------------------------------ | ------- | ------------------------------------ |
| organisationId<mark style="color:red;">\*</mark> | integer | The ID of the organisation           |
| entityId<mark style="color:red;">\*</mark>       | Integer | The ID of the entity to be retrieved |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status": "ok",
    "data": {
        "id": "287",
        "name": "Paris Saint-Germain Football Club",
        "type": "SoccerClub",
        "wikidata_id": "Q483020",
        "url_count": 4601,
        "last_30_days_page_views": 2095819
    }
}
```

{% endtab %}
{% endtabs %}

## Retrieve overal metrics for a particular query

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/communities/:communityId/contextual/analytics/overall_metrics`

#### Path Parameters

| Name                                             | Type    | Description                |
| ------------------------------------------------ | ------- | -------------------------- |
| organisationId<mark style="color:red;">\*</mark> | integer | The ID of the organisation |

{% tabs %}
{% tab title="200 " %}

```json
{
    "status":"ok",
    "data":
    {
        "url_count":13549,
        "last_30_days_page_views":4914430
    }
}
```

{% endtab %}
{% endtabs %}

## Retrieve panel based contextual targeting settings

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/audience_segments/:segmentId/contextual_targetings`

#### Path Parameters

| Name                                        | Type    | Description                             |
| ------------------------------------------- | ------- | --------------------------------------- |
| segmentId<mark style="color:red;">\*</mark> | integer | The ID of the audience segment on which |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status": "ok",
    "data": [
        {
            "type": "PANEL_BASED",
            "id": "1",
            "organisation_id": "1",
            "segment_id": "1",
            "volume_ratio": 0.8313403,
            "status": "LIVE",
            "live_activation_ts": 1678193619193,
            "last_lift_computation_ts": 1700100423716,
            "name": "Targeting_List_Name",
            "short_description": null,
            "token": "double-beer-maryland",
            "url_count": 3746,
            "last_30_days_page_views": 63824027,
            "created_ts": 1678193048401,
            "created_by": "1",
            "last_modified_ts": 1700055578893,
            "last_modified_by": "1",
            "archived": false
        }
    ],
    "count": 1,
    "total": 1,
    "first_result": 0,
    "max_results": 2147483647
}
```

{% endtab %}
{% endtabs %}

## Publish a contextual targeting (LIVE)&#x20;

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/audience_segments/:segmentId/contextual_targetings/:contextualTargetingId/actions`

#### Path Parameters

| Name                                                    | Type    | Description                                                       |
| ------------------------------------------------------- | ------- | ----------------------------------------------------------------- |
| segmentId<mark style="color:red;">\*</mark>             | integer | The ID of the audience segment on which                           |
| contextualTargetingId<mark style="color:red;">\*</mark> | Integer | The ID of the contextual targeting retrieved in creation response |

#### Request Body

| Name                                                    | Type             | Description                                                                                      |
| ------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------ |
| type<mark style="color:red;">\*</mark>                  | string           | "PUBLISH"                                                                                        |
| volume\_ratio<mark style="color:red;">\*</mark>         | float            | % of audience segment reach (30-day page views) that will be used to calculate lift              |
| activation\_platforms<mark style="color:red;">\*</mark> | array of strings | List of activation platforms where to activate the contexutal targeting. For instance \["XANDR"] |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status":"ok",
    "data": {
        "id":"143",
        "segment_id":"128765",
        "volume_ratio":0.33580595,
        "status":"PUBLISHED",
        "activation_platforms":["XANDR"],
        "live_activation_ts":null,
        "last_lift_computation_ts":1676542526247,
        "created_ts":1676542452678,
        "created_by":"3594",
        "last_modified_ts":1676543040147,
        "last_modified_by": "3594",
        "archived":false
    }
}
```

{% endtab %}
{% endtabs %}

## Archive a contextual targeting

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/audience_segments/:segmentId/contextual_targetings/:contextualTargetingId/actions`

#### Path Parameters

| Name                                                    | Type    | Description                                                       |
| ------------------------------------------------------- | ------- | ----------------------------------------------------------------- |
| segmentId<mark style="color:red;">\*</mark>             | integer | The ID of the audience segment on which                           |
| contextualTargetingId<mark style="color:red;">\*</mark> | Integer | The ID of the contextual targeting retrieved in creation response |

#### Request Body

| Name                                   | Type   | Description |
| -------------------------------------- | ------ | ----------- |
| type<mark style="color:red;">\*</mark> | string | "ARCHIVE"   |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status": "ok",
    "data": {
        "id": "143",
        "segment_id": "128765",
        "volume_ratio": 0.33580595,
        "status": "LIVE",
        "activation_platforms": [
            "XANDR"
        ],
        "live_activation_ts": 1676543074426,
        "last_lift_computation_ts": 1676542526247,
        "created_ts": 1676542452678,
        "created_by": "3594",
        "last_modified_ts": 1676548450358,
        "last_modified_by": "3594",
        "archived": true
    }
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.mediarithmics.io/advanced-usages/contextual-targeting/api-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.