> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/partner/global-api/placements/listplacements.md).

# Returns a list of placements

Returns a list of all placements

{% hint style="info" %}
Special character restriction

Special characters are currently not allowed in the namespace and environment fields due to backend validation. This limitation will be addressed in the upcoming release.
{% endhint %}

## Returns a list of placements

> Returns a list of all placements

```json
{"openapi":"3.0.0","info":{"title":"Citrus API","version":"1.1.0"},"tags":[{"description":"A placement is a single area of ad space within a retailer's site. Essentially, any placement on the retailer's site that needs to be individually selected will be a placement.","name":"Placements"}],"servers":[{"description":"Production","url":"https://api.citrusad.com/v1"},{"description":"Sandbox","url":"https://sandbox.api.citrusad.com/v1"},{"description":"Development","url":"https://dev-api.citrusad.com/v1"}],"security":[{"BearerToken":[]}],"components":{"securitySchemes":{"BearerToken":{"bearerFormat":"JWT","description":"For accessing the API a valid JWT token must be passed in all queries in\nthe 'Authorization' header. The following syntax must be used in the\n'Authorization' header.<br><br>\n\nBearer xxx.yyy.zzz\n","scheme":"bearer","type":"http"}},"schemas":{"PlacementPaginatedSchema":{"properties":{"links":{"$ref":"#/components/schemas/Links"},"placements":{"items":{"$ref":"#/components/schemas/Placement"},"type":"array"}},"required":["placements"]},"Links":{"properties":{"next":{"description":"The link to navigate to the next page.","type":"string"}},"type":"object"},"Placement":{"properties":{"adGenId":{"description":"Immutable Ad generation identifier","type":"string"},"archived":{"description":"Indicates if the placement is archived. Placement still exists and existing campaigns with this placement still work, but creating new one is not possible.","type":"boolean"},"blockedFilters":{"description":"Blocked filters for campaign requests","items":{"description":"Blocked filter","type":"string"},"type":"array"},"campaignTypes":{"description":"Array of campaign types supported by the placement","items":{"$ref":"#/components/schemas/CampaignType"},"minItems":1,"readOnly":true,"type":"array","uniqueItems":true},"catalogIds":{"description":"Array of catalog IDs associated with the placement","items":{"description":"Unique identifier of a catalog","type":"string"},"minItems":1,"type":"array","uniqueItems":true},"customTooltipText":{"description":"Custom tooltip text","type":"string"},"displayName":{"description":"Human readable name of the placement. Useful for showing within a client application","type":"string"},"id":{"description":"Unique identifier of the placement","readOnly":true,"type":"string"},"namespace":{"description":"Namespace for the placement","type":"string"},"targeting":{"$ref":"#/components/schemas/PlacementTargeting"}},"required":["id","adGenId","displayName","catalogIds","campaignTypes","namespace","targeting","blockedFilters"],"type":"object"},"CampaignType":{"description":"The type of campaign supported by Citrus Ad","enum":["BANNER","DISPLAY","BANNER_X","BRAND_PAGE"],"type":"string"},"PlacementTargeting":{"description":"The type of ad placement the campaign will target. For example, if the campaignTarget is SEARCH_ONLY then these will be search ads and the relevant configuration for this ad type is described in SearchConfig.","properties":{"campaignTarget":{"$ref":"#/components/schemas/CampaignTarget"},"categoryConfig":{"$ref":"#/components/schemas/CategoryConfig"},"customTargetedLocationsAllowed":{"description":"Indicates if custom targeted locations are allowed","type":"boolean"},"searchConfig":{"$ref":"#/components/schemas/SearchConfig"}},"required":["customTargetedLocationsAllowed"],"type":"object"},"CampaignTarget":{"description":"Targeting strategy for campaigns","enum":["SEARCH_ONLY","CATEGORY_AND_SEARCH","CATEGORY_ONLY","BROAD_DISPLAY","CROSS_SELL","UPSELL","RUN_OF_SITE","CATEGORY_CROSS_SELL"],"type":"string"},"CategoryConfig":{"description":"Configuration for category targeting, only available when `campaignTarget` is CATEGORY_ONLY or CATEGORY_AND_SEARCH","properties":{"customTargetedCategoriesAllowed":{"description":"Indicates if custom targeted categories are allowed","type":"boolean"}},"required":["customTargetedCategoriesAllowed"],"type":"object"},"SearchConfig":{"description":"Configuration for search targeting, only available when `campaignTarget` is SEARCH_ONLY","properties":{"customSearchTermAllowed":{"description":"Indicates if custom search terms are allowed","type":"boolean"},"searchTermTypeLabel":{"description":"Label for search term type","type":"string"},"suggestedSearchTermEnabled":{"description":"Indicates if suggested search terms are enabled","type":"boolean"},"suggestedSearchTermType":{"$ref":"#/components/schemas/SearchTermType"}},"required":["suggestedSearchTermEnabled","customSearchTermAllowed"],"type":"object"},"SearchTermType":{"description":"Type of suggested search term","enum":["CROSS_SELL","ORGANIC","SUBSTITUTE","UNDEFINED"],"type":"string"},"Error":{"properties":{"message":{"description":"Error message returned from the API","type":"string"}},"required":["message"],"type":"object"}},"responses":{"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized. This request could not be processed due to an invalid token.<br><br>\nPossible example error messages:<br> - `Unauthorized`<br> - `Failed to parse token`: The token is not in the correct format, or has expired.<br> - `token can't be empty`: Missing Authorization Bearer token in header\n"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden. This request could not be processed due a token that does not have permission to access the requested resource.<br><br>\nPossible example error messages:<br> - `Forbidden`\n"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too many requests. This request could not be processed as the rate limit has been exceeded.<br><br>\nPossible example error messages:<br> - `Too many requests`\n"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Generic Error. The request could not be processed due to an unknown error.<br><br>\n"}}},"paths":{"/placements":{"get":{"description":"Returns a list of all placements","operationId":"listPlacements","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacementPaginatedSchema"}}},"description":"Expected response to a valid request"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"429":{"$ref":"#/components/responses/429"},"default":{"$ref":"#/components/responses/default"}},"summary":"Returns a list of placements","tags":["Placements"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.citrusad.com/retail-media-interface/partner/global-api/placements/listplacements.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.