# Nonli Developer API > API documentation for clients and AI agents integrating with Nonli. Base URL: https://api.nonli.com/v2.1 OpenAPI: https://www.nonli.com/api-docs/openapi.json Human documentation: https://www.nonli.com/en/developers Authentication: - Create an API token from the Nonli back office. - Send it on authenticated calls using Authorization: Bearer YOUR_API_TOKEN. - API tokens represent a company role, not a web user session. Do not use /me with Bearer tokens. - To validate a token, call GET /brands?size=1&fields=id,name. Common query grammar: - filters uses semicolon-separated AND filters, for example filters=brandId:1;status:200. - filtersOr uses OR values, for example filtersOr=status:200,203. - ranges use two dots, for example publishedAt:2024-05-01T00:00:00Z..2024-05-31T23:59:59Z. - Send the filter separators (colon, semicolon, comma, double dot) as raw characters. Search endpoints read the raw query string, so percent-encoded separators such as %3A are treated as literal value characters and the filter silently matches nothing or returns 400. Percent-encode only characters inside values, such as spaces (%20). - fields limits returned fields and should be used by agents to reduce payload size. - Post-backed endpoints accept the documented post counters in counter filters and counter sorts. Historical counter names replaced by public counter names are intentionally omitted. - Organic Listening, Shortlink, and Accounts endpoints expose their own standard counters and reject post counters. - The leaderboard aggregationField accepts the documented post counter names; the API resolves them to stored counters internally. Available standard counters: - Posts, Social Listening, and Bots (/posts, /posts/categories, /posts/brands, /posts/users, /posts/languages, /posts/histogram, /posts/aggregation, /posts/stats, /posts/tags, /posts/topics, /posts/leaderboard, /posts/leaderboard/_search, /posts/leaderboard/categories, /listening/social, /bots/bulk): click, click_unique, ctr, engagement, facebook_engagement_per_minute, weighted_facebook_engagement, weighted_facebook_engagement_per_minute, facebook_comment, facebook_total_reaction, facebook_share, reach, impression, videoViews, video_views_3sec, facebook_post_video_avg_time_watched, video_completion_rate, overperforming, reposts, quotes, monetization, snapchat_screenshots, subscriber, facebook_link_clicks, facebook_other_clicks, facebook_photo_view, facebook_video_play, facebook_post_video_views_60s_excludes_shorter, instagram_saved, instagram_total_interactions, instagram_clips_replays_count, linkedin_private_click_count, youtube_likes, youtube_dislikes, youtube_estimated_minutes_watched. Use these names in post-backed counter filters, counter sorts, bot trigger counters, and bot post-rate metrics. Facebook reach is requested as `reach`; the API maps the current Meta reach metric internally. TikTok metrics currently feed the common post counters `engagement`, `facebook_total_reaction`, `facebook_comment`, `facebook_share`, `videoViews`, and `impression`, instead of dedicated TikTok counters. Historical counter names replaced by these public names, and counters that are no longer available from network APIs, are intentionally omitted. - Organic Listening (/listening/organic, /listening/organic/stats, /listening/organic/aggregation): click, new_lead, quantity, amount, paywall_view, paywall_unlocked, paywall_click, paywall_subscribe_click, paywall_login_click, subscription_complete, comment_count, video_views, view_in_stock, view_out_of_stock, price, price_variation, low_price, high_price, rating, review_count, stock. Use these names for standard Organic Listening counter filters and sorts. Legacy Organic counters are intentionally excluded from the public API surface. - Shortlinks (/shortlinks, /shortlinks/:shortlinkId, /shortlinks/stats, /shortlinks/authors, /shortlinks/brands): click. Shortlink counter endpoints only expose shortlink counters and reject post counters. - Accounts (/accounts, /accounts/stats): follower_count. Use the full counter path on Accounts endpoints, for example sort=-counters.total.follower_count or filters=counters.graph.counter:follower_count. The counter sort shorthand (sort=-follower_count) also resolves. The documented name is resolved to the stored account counter internally; historical internal counter names are intentionally omitted. Post counters such as engagement, reach, or videoViews are invalid for Accounts. Conventions: - Responses echo the counter names the request used: request counters by their documented public names (engagement, follower_count, ...) and counters come back under those names; request stored names and stored names come back. - List endpoints return total plus a rows array; page with size and a zero-based page until total items are collected. - Timestamps are UTC ISO-8601, for example 2026-05-27T23:59:59Z. - Identifiers are string UUIDs for posts, shortlinks, and organic items, hash strings for listening accounts, and integers for brands, connected social accounts, and themes. - The API token is a bearer credential; store it securely, rotate it from the back office, and do not put it in query strings. Errors: - Branch on the HTTP status code rather than parsing error message text. - 400 bad request, 401 unauthorized (check or rotate the API token), 403 forbidden, 404 not found, 429 rate limited (back off and retry), 5xx server error. Core endpoints: - GET /brands: Search brands. Return the brands visible to the API token role in the authenticated company. - GET /brands/:brandId: Get a brand. Return one brand with optional embedded configuration used for publishing, shortlinks, smart images, and URL parameters. - GET /social-accounts: Search social accounts. Return social accounts available to the authenticated company and user. - GET /social-accounts/:socialAccountId: Get a social account. Return one connected social account with publishing metadata. - GET /social-accounts/publishing-quota: Get publishing quota. Return publishing quota information for selected social accounts before scheduling posts. - GET /social-accounts/youtube/playlists: Get YouTube playlists. Return YouTube playlists for connected YouTube social accounts. - GET /social-accounts/pinterest/boards: Get Pinterest boards. Return Pinterest boards for connected Pinterest social accounts. - GET /posts: Search posts. Search posts published or scheduled through Nonli. Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted. - GET /posts/:postId: Get a post. Return one post by ID with optional filters and field selection. - GET /posts/categories: Get post categories. Return category aggregations used by post filters and dashboards. Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted. - GET /posts/brands: Get post brands. Return brand aggregations for posts visible to the API token role. Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted. - GET /posts/users: Get post users. Return user aggregations for post author and collaboration filters. Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted. - GET /posts/languages: Get post languages. Return language aggregations for post filters. Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted. - GET /posts/histogram: Get post histogram. Return time-bucketed post counts or counter values for graphing. Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted. - GET /posts/aggregation: Get post aggregation. Return generic aggregations for post dashboards and filter facets. Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted. - GET /posts/stats: Get post stats. Return aggregated post performance statistics for dashboard widgets. Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted. - POST /posts/check: Check post content. Validate post content before publishing. The BO uses this endpoint to surface publication warnings. - GET /posts/tags: Get post tags. Return matching tags for autocomplete and reporting filters. Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted. - GET /posts/topics: Get post topics. Return matching topics for autocomplete and reporting filters. Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted. - POST /posts/bulk: Create posts in bulk. Create a collection of posts. Use postType "flying" with a shortlink mappingId to publish a flying link. - PUT /posts/bulk: Update posts in bulk. Update a collection of posts. Send post.id and, when available, createdAt to optimize lookup. - DELETE /posts/bulk: Delete posts in bulk. Delete a collection of posts. The async flag can be used for background deletion. - GET /shortlinks: Search shortlinks. Search shortlinks and retrieve counters, target URLs, metadata, and publication information. Shortlink counter endpoints accept shortlink counters only, currently `click`. Post counters such as `engagement`, `reach`, or `videoViews` are invalid for Shortlinks. - GET /shortlinks/:shortlinkId: Get a shortlink. Return one shortlink by ID with optional counters and field selection. Shortlink counter endpoints accept shortlink counters only, currently `click`. Post counters such as `engagement`, `reach`, or `videoViews` are invalid for Shortlinks. - GET /shortlinks/stats: Get shortlink stats. Return aggregated shortlink performance statistics. Shortlink counter endpoints accept shortlink counters only, currently `click`. Post counters such as `engagement`, `reach`, or `videoViews` are invalid for Shortlinks. - GET /shortlinks/authors: Get shortlink authors. Return author aggregations used by shortlink filters. Shortlink counter endpoints accept shortlink counters only, currently `click`. Post counters such as `engagement`, `reach`, or `videoViews` are invalid for Shortlinks. - GET /shortlinks/brands: Get shortlink brands. Return brand aggregations used by shortlink filters. Shortlink counter endpoints accept shortlink counters only, currently `click`. Post counters such as `engagement`, `reach`, or `videoViews` are invalid for Shortlinks. - POST /shortlinks: Create a shortlink. Create or extract a shortlink for a target URL. - POST /shortlinks/bulk: Create shortlinks in bulk. Create several shortlinks in one request. - PUT /shortlinks/:shortlinkId: Update a shortlink. Update target URL, metadata, images, brand association, and sponsor information for a shortlink. - POST /shortlinks/:shortlinkId/generate-message: Generate a message for a shortlink. Generate suggested social copy for a shortlink and content type. - GET /themes: Search themes. Return team, bot, or public themes visible to the API token role. - GET /themes/:themeId: Get a theme. Return one saved theme by ID. - POST /themes: Create a theme. Create a saved theme from listening or post filters. - PUT /themes/:themeId: Update a theme. Update a saved theme and rebuild its query strings when the value changes. - DELETE /themes/:themeId: Delete a theme. Delete a saved theme. - GET /themes/roles: Get theme roles. Return roles that can be associated with team-scoped themes. - GET /listening/social: Get social listening. Search social posts and counters collected from supported social networks. Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted. - GET /listening/organic: Get organic listening. Search website content indexed by Organic Listening. Organic Listening endpoints accept standard Organic Listening counters only. Post counters such as `engagement`, `reach`, or `videoViews` are invalid for Organic Listening and return 400 Bad Request. - GET /listening/organic/:organicId: Get organic content. Return one indexed organic content item by ID. - GET /listening/organic/stats: Get organic stats. Return aggregated Organic Listening performance statistics. Organic Listening endpoints accept standard Organic Listening counters only. Post counters such as `engagement`, `reach`, or `videoViews` are invalid for Organic Listening and return 400 Bad Request. - GET /listening/organic/aggregation: Get organic aggregation. Return generic aggregations for Organic Listening dashboards and filters. Organic Listening endpoints accept standard Organic Listening counters only. Post counters such as `engagement`, `reach`, or `videoViews` are invalid for Organic Listening and return 400 Bad Request. - GET /listening/organic/suggest/:field: Suggest organic filter values. Return autocomplete suggestions for an Organic Listening field. - GET /posts/leaderboard: Get the leaderboard. Return social accounts ranked by an aggregated post counter, with per post type breakdowns and account profile data. aggregationField and additionalAggregationFields accept the documented post counter names, such as engagement, reach, videoViews, click, ctr, overperforming, or monetization. The API resolves each documented name to the stored counter internally; historical internal counter names are intentionally undocumented. Counters built from public network data, such as engagement or videoViews, rank any listened account. Counters that require account ownership automatically restrict the leaderboard to social accounts the API token can access. Leaderboard filters and sorts accept the shorthand fields name, slug, category, and verificationStatus, resolved to the matching socialAccount fields internally. - POST /posts/leaderboard/_search: Search the leaderboard. Same ranking as GET /posts/leaderboard with parameters sent in the JSON body. Use it when the filter set exceeds URL length limits, for example large theme filters. aggregationField and additionalAggregationFields accept the documented post counter names, such as engagement, reach, videoViews, click, ctr, overperforming, or monetization. The API resolves each documented name to the stored counter internally; historical internal counter names are intentionally undocumented. Counters built from public network data, such as engagement or videoViews, rank any listened account. Counters that require account ownership automatically restrict the leaderboard to social accounts the API token can access. Leaderboard filters and sorts accept the shorthand fields name, slug, category, and verificationStatus, resolved to the matching socialAccount fields internally. - GET /posts/leaderboard/categories: Get leaderboard categories. Return the per post type counter breakdown for selected leaderboard accounts. aggregationField and additionalAggregationFields accept the documented post counter names, such as engagement, reach, videoViews, click, ctr, overperforming, or monetization. The API resolves each documented name to the stored counter internally; historical internal counter names are intentionally undocumented. - GET /accounts: Search accounts. Search social accounts tracked by Social Listening, with profile data and account counters. Accounts endpoints expose account counters only, currently follower_count (account fans or followers). The API resolves this documented name to the stored account counter internally, and responses echo the name the request used. Address it with the full counter path, for example sort=-counters.total.follower_count or filters=counters.graph.counter:follower_count. Post counters such as engagement or reach are invalid for Accounts. The category filter and query field resolve to the localized account category internally; filter with category: rather than a localized field path. - POST /accounts: Add an account. Add a social account to Social Listening. The account is fetched from the network, activated for listening, and returned. Requires a role with the listening manage permission. - GET /accounts/categories: Get account categories. Return account category aggregations for autocomplete and listening filters. The category filter and query field resolve to the localized account category internally; filter with category: rather than a localized field path. - GET /accounts/locations: Search account locations. Return location accounts, such as city pages, matching a query. Local index results are combined with a remote network search. A type filter selecting the social network is required. - GET /accounts/stats: Get account stats. Return aggregated account counter statistics with optional trend and histogram data. Accounts endpoints expose account counters only, currently follower_count (account fans or followers). The API resolves this documented name to the stored account counter internally, and responses echo the name the request used. Address it with the full counter path, for example sort=-counters.total.follower_count or filters=counters.graph.counter:follower_count. Post counters such as engagement or reach are invalid for Accounts. - GET /bots: Search bots. Return bots visible to the API token role in the authenticated company. - GET /bots/:botId: Get a bot. Return one bot by UUID. - POST /bots/bulk: Create bots in bulk. Create one or more bots. Source and target URNs must reference resources visible to the API token role. Bot trigger counters and post-rate metrics use the documented post counters. Percentile-based triggers resolve the documented counter name before calculating the percentile. - PUT /bots/bulk: Update bots in bulk. Update one or more bots. Each item must include the bot UUID and only the fields to change. Bot trigger counters and post-rate metrics use the documented post counters. Percentile-based triggers resolve the documented counter name before calculating the percentile. - DELETE /bots/:botId: Delete a bot. Delete one bot by UUID. A successful deletion returns HTTP 204 with no response body. - GET /bots/info: Get bot configuration info. Return schedule periods, target validation rules, and bot configuration constraints used to build valid bot payloads. - GET /media: Search media. Return media items available to the current company and user. - GET /media/tags: Get media tags. Return media tags for autocomplete and asset filtering. - POST /upload/image: Upload an image. Upload a base64 image and receive the Fontan slug used by posts and shortlinks. - POST /upload/video/token: Create upload video token. Create or resume an upload session. The response includes chunkSize, which defines the maximum chunk size to send. - POST /upload/video/exists: Check uploaded video existence. Check if a video already exists before starting a chunked upload. - POST /upload/video/chunk: Upload video chunk. Upload one base64 chunk for a video upload session. The final response includes the video id and URL. - POST /upload/document/token: Create upload document token. Create or resume a document upload session. The response includes chunkSize for chunked upload. - POST /upload/document/chunk: Upload document chunk. Upload one base64 chunk for a document upload session. The final response includes the document id and URL. Recommended agent flow: load the Bearer token from a secret store, request only needed fields, page through results with size/page, and respect rate limits.