zelf

func (*AIAnalysisResource) ContentStatistics ¶

func (r *AIAnalysisResource) ContentStatistics(ctx context.Context, params *AiAnalysisContentStatisticsParams) (*ContentStatistics, error)

ContentStatistics returns aggregate totals (post count, views, engagement, earned media value, and unique creators) over the content an AI analysis ran over. Requires `analysis_id` (an analysis `id` from `ai_analysis.list`) and returns the same totals shape as `content.statistics`.

Calls GET /api/v1/ai_analysis/contents/statistics/ (ai_analysis.content_statistics).

func (*AIAnalysisResource) Contents ¶

func (r *AIAnalysisResource) Contents(ctx context.Context, params *AiAnalysisContentsParams) (*Page[Content], error)

Contents returns the content an AI analysis ran over, in the standard content shape. Use it to inspect the exact posts included in an analysis. Requires `analysis_id` (an analysis `id` from `ai_analysis.list`). Brand-scoped fields (`is_owned`, `is_tagged`, `net_promoter_score`, ...) are `null` in this response.

Calls GET /api/v1/ai_analysis/contents/ (ai_analysis.contents).

func (*AIAnalysisResource) Create ¶

func (r *AIAnalysisResource) Create(ctx context.Context, body AiAnalysisCreateJSONRequestBody) (*AiAnalysis, error)

Create starts an AI analysis over the content matched by `content_filters` (or its comments) for a given `topic`. Runs complete asynchronously; this method returns immediately with the created analysis and its initial runs. The analysis runs over the highest-ranked matching content by `content_filters.order_by`, up to 500 posts or the limit configured for your workspace. When `order_by` is omitted, content is ranked by `earned_media_value_cents` descending. The created analysis is returned as the single item in `results`. Take its `id` and poll `ai_analysis.list` until a run reports `COMPLETED`. An analysis can take an hour or more, so poll at a moderate interval; prefer the `ai_analysis.completed` webhook over frequent polling, which can trigger `RATE_LIMIT_EXCEEDED`. Once complete, retrieve the payload from `ai_analysis.results`, passing `analysis_id=<id>`.

Calls POST /api/v1/ai_analysis/ (ai_analysis.create).

func (*AIAnalysisResource) List ¶

func (r *AIAnalysisResource) List(ctx context.Context, params *AiAnalysisListParams) (*Page[AiAnalysis], error)

List returns the AI analyses that have been created, ordered newest first, each with its runs and their current `status`. It lists the analyses available and tracks run progress without retrieving the full result payload. An analysis `id` maps to `analysis_id` on `ai_analysis.results` and `ai_analysis.contents`, and each run's `id` maps to `id` on `ai_analysis.results`. The run `result` download is not included in this response; retrieve it from `ai_analysis.results` once a run reports `COMPLETED` (statuses: `IN_PROGRESS`, `COMPLETED`, `EMPTY_RESULT`, `FAILED`). Supply `id` to return a single analysis.

Calls GET /api/v1/ai_analysis/ (ai_analysis.list).

func (*AIAnalysisResource) Results ¶

func (r *AIAnalysisResource) Results(ctx context.Context, params *AiAnalysisResultsParams) (*Page[AiAnalysisResult], error)

Results returns each run's `result`, a signed, time-limited download of the analysis payload. Call this method after a run reaches `COMPLETED`; for earlier statuses the row is returned with a `null` `result`. Supply `analysis_id` (the analysis `id` from `ai_analysis.list`) to return every run of that analysis, or `id` (a single run's `id`) to return one run. Exactly one is required. A malformed id returns `INVALID_ID`; omitting both returns `VALIDATION_ERROR`.

Calls GET /api/v1/ai_analysis/results/ (ai_analysis.results).

func (*APIError) Error ¶

func (e *APIError) Error() string

func (*APIError) Is ¶

func (e *APIError) Is(target error) bool

Is lets errors.Is(err, zelf.ErrRateLimit) match on status alone.

func (*AnalyticsResource) BrandComparison ¶ added in v1.1.0

func (r *AnalyticsResource) BrandComparison(ctx context.Context, params *AnalyticsBrandComparisonParams) (*BrandComparison, error)

BrandComparison returns one row of totals per brand: the top-level brand named by `brand_id`, followed by each of its competitor sub-brands. The statistics block matches `content.statistics`, so the same parsing works for both. `brand_id` must name a top- level brand. A sub-brand is refused with the id of the parent to use instead.

Calls GET /api/v1/analytics/brand_comparison/ (analytics.brand_comparison).

func (*AnalyticsResource) FollowerTimeseries ¶ added in v1.1.0

func (r *AnalyticsResource) FollowerTimeseries(ctx context.Context, params *AnalyticsFollowerTimeseriesParams) (*FollowerTimeseries, error)

FollowerTimeseries returns follower history for the top-level brand named by `brand_id` and each of its competitor sub-brands, bucketed by `period`. A brand appears only for the periods in which one of its owned handles was measured. Follower counts carry forward: a handle with no reading in a period keeps the last one recorded before it.

Calls GET /api/v1/analytics/follower_timeseries/ (analytics.follower_timeseries).

func (*AnalyticsResource) PostedComments ¶ added in v1.1.0

func (r *AnalyticsResource) PostedComments(ctx context.Context, params *AnalyticsPostedCommentsParams) (*PostedComments, error)

PostedComments returns the comments the brand posted in the window, grouped by the kind of content they were posted on, together with the likes and replies those comments received. These are comments the brand wrote, not comments left on its content; `comments.list` returns the latter. The five categories add up to `total_comments_posted`.

Calls GET /api/v1/analytics/posted_comments/ (analytics.posted_comments).

func (*BrandAccountsResource) Add ¶

func (r *BrandAccountsResource) Add(ctx context.Context, body BrandAccountsAddJSONRequestBody) ([]BrandAccountGroups, error)

Add adds profiles to a brand's `tracked`, `influencer` or `owned` list. Use `owned` for the brand's own profiles. Each `profile_url` is matched and deduplicated by `(platform, username)`, so re-adding an existing account has no effect. URLs that cannot be parsed fail validation on `profile_urls`. Supply `brand_id` in the request body to target another brand; otherwise the brand the key acts on is used. Any brand listed by `brands.list` is a valid target, which includes linked top-level brands and their sub- brands.

Calls POST /api/v1/brands/accounts/ (brand_accounts.add).

func (*BrandAccountsResource) List ¶

func (r *BrandAccountsResource) List(ctx context.Context, params *BrandAccountsListParams) ([]BrandAccountGroups, error)

List returns a brand's tracked and influencer creator accounts, plus the `owned` accounts the brand operates itself. Defaults to the brand the key acts on. Supply `brand_id` to target another brand listed by `brands.list`, which includes linked top- level brands and their sub-brands. Restrict the response to a single list with the `account_type` parameter (`tracked`, `influencer` or `owned`).

Calls GET /api/v1/brands/accounts/ (brand_accounts.list).

func (*BrandAccountsResource) Remove ¶

func (r *BrandAccountsResource) Remove(ctx context.Context, body BrandAccountsRemoveJSONRequestBody) ([]BrandAccountGroups, error)

Remove removes profiles from a brand's `tracked`, `influencer` or `owned` list. This operation is destructive; call it only when the intent is to stop following these accounts. Profiles are matched by `(platform, username)` parsed from each `profile_url`. Returns the updated list. Supply `brand_id` in the request body to target another brand; otherwise the brand the key acts on is used. Any brand listed by `brands.list` is a valid target, which includes linked top-level brands and their sub-brands.

Calls DELETE /api/v1/brands/accounts/ (brand_accounts.remove).

func (*BrandsResource) Catalog ¶

func (r *BrandsResource) Catalog(ctx context.Context, params *BrandsCatalogParams) (*Page[BrandCatalog], error)

Catalog returns the brands Zelf curates for competitive benchmarking. Every api key can read content for these brands, whether or not they are linked to yours, so this is where to look for a competitor that is not one of your own sub-brands. Each row's `id` is the value to supply as `brand_id` on the content and AI analysis endpoints; the brand write endpoints do not accept it. Narrow the list with `search` (title substring), `industry_id`, or `category_id`; the id values for the last two come from `brands.catalog_categories`.

Calls GET /api/v1/brands/catalog/ (brands.catalog).

func (*BrandsResource) CatalogCategories ¶

func (r *BrandsResource) CatalogCategories(ctx context.Context) ([]BrandCatalogItem, error)

CatalogCategories returns every industry and the categories under it, as one flat list. An industry has `level: industry` and a null `parent_id`; a category has `level: category` and the `parent_id` of its industry. Each `id` is the value to supply as `industry_id` or `category_id` to `brands.catalog`.

Calls GET /api/v1/brands/catalog/categories/ (brands.catalog_categories).

func (*BrandsResource) List ¶

func (r *BrandsResource) List(ctx context.Context, params *BrandsListParams) (*Page[Brand], error)

List returns every brand this key can reach: the workspace brand, every brand linked to it, and the sub-brands of each. Start here when building a new integration, to find out which brand ids are available. Each row's `id` is the value to supply as `brand_id` wherever a brand is named. `is_primary` identifies the workspace brand, and `parent_brand_id` links a sub-brand to its parent.

Calls GET /api/v1/brands/ (brands.list).

func (*BrandsResource) Update ¶

func (r *BrandsResource) Update(ctx context.Context, body BrandsUpdateJSONRequestBody) (*Brand, error)

Update partially updates a brand's monitoring keywords. Only the supplied fields are modified. Targets the brand the key acts on unless `brand_id` is provided in the request body. Any brand listed by `brands.list` is a valid target. That list holds every brand linked to the key, each linked brand's sub-brands, and the key's own brand. A single key therefore reaches whole brand families, often dozens of brands, and this endpoint writes to all of them. Returns the updated brand.

Calls PATCH /api/v1/brands/ (brands.update).

func (*Client) BaseURL ¶

func (c *Client) BaseURL() string

BaseURL reports the endpoint the client talks to. The API key is deliberately not exposed on Client.

func (*CommentsResource) List ¶

func (r *CommentsResource) List(ctx context.Context, params *CommentsListParams) (*Page[Comment], error)

List returns a paginated list of comments, ordered by newest first. At least one filter is required to scope the query. Filter by `content_id` (a content `id`) to retrieve the comments on a piece of content, by `id` to retrieve a single comment, or by `parent_comment_id` to retrieve the replies to a comment. A request that supplies none of these returns `INVALID_ID`.

Calls GET /api/v1/comment/ (comments.list).

func (*ConnectionError) Error ¶

func (e *ConnectionError) Error() string

func (*ConnectionError) Unwrap ¶

func (e *ConnectionError) Unwrap() error

func (*ContentResource) AISummarize ¶

func (r *ContentResource) AISummarize(ctx context.Context, body ContentAiSummarizeJSONRequestBody) (*ContentActionResponse, error)

AISummarize writes a short AI summary of what the content is about. Returns `202` with `status: PENDING` when a run starts. Call again to follow it: `PENDING` while it runs, `COMPLETED` once the content has a summary, `FAILED` if all 3 tries failed.

Calls POST /api/v1/content/ai_summarize/ (content.ai_summarize).

func (*ContentResource) Details ¶

func (r *ContentResource) Details(ctx context.Context, id string, params *ContentDetailsParams) (*Content, error)

Details returns a single piece of content identified by `id`. Supply `brand_id` to additionally require the content to exist under that brand and to populate the brand- specific fields. If the content does not exist under that brand, the response is an empty result set rather than a 404. When `brand_id` is omitted, the brand-specific fields are returned as `null`.

Calls GET /api/v1/content/{id}/ (content.details).

func (*ContentResource) Discover ¶

func (r *ContentResource) Discover(ctx context.Context, body ContentDiscoverJSONRequestBody) (*ContentDiscovery, error)

Discover starts an asynchronous job that indexes fresh content matching a search term across the requested platforms. Use it to ingest content Zelf does not yet cover. The response describes the job, not the content itself. Once the job completes, query `content.list` to retrieve the indexed content. An identical term requested again within the deduplication window reuses the in-flight job and returns `dispatched: false` instead of starting a new one.

Calls POST /api/v1/content/discovery/ (content.discover).

func (*ContentResource) List ¶

func (r *ContentResource) List(ctx context.Context, params *ContentListParams) (*Page[Content], error)

List returns a paginated list of content. Every request must scope what it covers: supply at least one of `creator_id`, `creator_username`, `search`, `brand_id`, or `external_id`, otherwise the request is rejected with `VALIDATION_ERROR`. By default results are ordered by `posted_at` descending (most recently posted first); override with `order_by`. Every response echoes the effective defaults in `applied_filters` (the resolved date window, `page`, `page_size`, and `brand_id`), so an empty `results` set can be explained. ### Dates Every request covers a time window. Four parameters define it. | Parameter | Type | Defines | |---|---|---| | `posted_after` | timestamp | Start of the window | | `posted_within_hours` | integer, 1 to 8760 | Start of the window, counted back from the current time | | `posted_within_days` | integer, 1 to 365 | Start of the window, counted back from the current time | | `posted_before` | timestamp | End of the window | A request with no date parameter covers the last 7 days. `applied_filters` reports this as `posted_within_days: 7`. Three parameters define the start of the window, so a request may carry more than one. Such a request is valid. The API applies the first parameter present in this order and ignores the rest: 1. `posted_after` 2. `posted_within_hours` 3. `posted_within_days` `applied_filters` contains only the parameter that was applied, so it identifies the window that produced a response. `posted_before` defines the end of the window and combines with any of the three. On its own it covers the 366 days before it. With `posted_within_hours` or `posted_within_days` the window is counted back from `posted_before` instead of from the current time, so `posted_before=2026-09-01T00:00:00Z` with `posted_within_hours=24` covers `2026-08-31T00:00:00Z` to `2026-09-01T00:00:00Z`. Two limits apply to every window. `posted_after` and `posted_before` may be at most 366 days apart, and a longer period is read as consecutive requests. Content posted before 2025-01-01 is not available. A value outside the ranges in the table returns `VALIDATION_ERROR`. Such values are rejected, not clamped: `posted_within_days=400` is an error rather than 365. Results are paginated: `page` defaults to `1` and `page_size` to `30`, which is also the maximum (larger values are reduced to `30`). `item_count` is the number of rows in the returned page, not the size of the whole match set, and `next` is non-null while further pages remain. For the total number of matching posts, call `content.statistics` with the same query and read `post_count`. When `brand_id` is omitted, the brand-specific fields (`brand_id`, `is_owned`, `is_tagged`, `is_influencer`, `mention_type`, `net_promoter_score`) are returned as `null`, and the brand-only filters and sorts return `BRAND_ID_REQUIRED`. Supply `brand_id` (one or more values, comma-separated) to populate those fields and enable the brand-only filters. Each row's `id` is the value to use for `content.details` and for the `comments.list` `content_id`.

Calls GET /api/v1/content/ (content.list).

func (*ContentResource) Statistics ¶

func (r *ContentResource) Statistics(ctx context.Context, params *ContentStatisticsParams) (*ContentStatistics, error)

Statistics returns a single aggregate of reach, engagement, value, and creator counts over the **same content set** that `content.list` would return for an identical query. The `post_count` is the number of posts in that whole set, across every page the list would return, and each other total is the sum over those same posts. `content.list` never counts the full set: its `item_count` is only the number of rows in the page it returned, so `post_count` here is the only total available. This accepts every filter `content.list` accepts and applies the **same defaults** and requirements: every request must scope what it covers with at least one of `creator_id`, `creator_username`, `search`, `brand_id`, or `external_id` (else `VALIDATION_ERROR`); brand-only filters and sorts still require `brand_id`. `order_by` is validated the same as in `content.list` (brand-only sorts still require `brand_id`) but has no effect on the aggregated totals. Returns a single totals object (`item_count: 1`), not paginated, and echoes the resolved date window and `brand_id` in `applied_filters`. ### Dates `content.statistics` takes the same four date parameters as `content.list` and applies them identically. `posted_after`, `posted_within_hours` (1 to 8760) and `posted_within_days` (1 to 365) define the start of the window; `posted_before` defines the end. A request with no date parameter covers the last 7 days. A request carrying more than one start parameter is valid, and the first present in the order `posted_after`, `posted_within_hours`, `posted_within_days` is applied; `applied_filters` reports that one. `posted_after` and `posted_before` may be at most 366 days apart. Both endpoints apply these parameters identically, so one set of dates covers the same posts on each. `post_count` is therefore the size of the set `content.list` pages through. Supply `brand_id` (one or more values, comma-separated) to scope the totals the same way the list does. Each piece of content is counted once even when several `brand_id` values match it.

Calls GET /api/v1/content/statistics/ (content.statistics).

func (*ContentResource) Transcribe ¶

func (r *ContentResource) Transcribe(ctx context.Context, body ContentTranscribeJSONRequestBody) (*ContentActionResponse, error)

Transcribe transcribes the speech in the content's audio or video into text. Returns `202` with `status: PENDING` when a run starts. Call again to follow it: `PENDING` while it runs, `COMPLETED` once the content has a transcription, `FAILED` if all 3 tries failed.

Calls POST /api/v1/content/transcribe/ (content.transcribe).

func (*CreatorSyncResource) Create ¶

func (r *CreatorSyncResource) Create(ctx context.Context, body CreatorSyncCreateJSONRequestBody) (*CreatorSync, error)

Create add a creator's profile and posts to Zelf so their videos can be analyzed. Send the creator's `profile_url`. Zelf reads and stores the profile and the creator's own posts, which then appear in `creators.list` and `content.list`. Syncing is asynchronous. This method returns immediately with the sync at `status: SYNCING`. Poll `creator_sync.get` until `status` is `SUCCESS` or `FAILED`. Only the creator's own posts are synced. Reposts and posts they are tagged in are not. Synced content is not attached to your brand, so it does not appear in brand-scoped totals.

Calls POST /api/v1/creator_sync/ (creator_sync.create).

func (*CreatorSyncResource) Get ¶

func (r *CreatorSyncResource) Get(ctx context.Context, id string) (*CreatorSync, error)

Get returns a single creator sync job identified by `id`, the value returned by `creator_sync.create` or reported by a vetting as `sync_job_id`. Poll it until `status` reports `SUCCESS` or `FAILED`.

Calls GET /api/v1/creator_sync/{id}/ (creator_sync.get).

func (*CreatorSyncResource) List ¶

func (r *CreatorSyncResource) List(ctx context.Context, params *CreatorSyncListParams) (*Page[CreatorSync], error)

List returns creator sync jobs ordered newest first, each with its current `status`. Use it to monitor progress after `creator_sync.create`. Possible statuses are `SCHEDULED`, `SYNCING`, `SUCCESS` and `FAILED`. A job's `creator_id` is `null` until the creator has been resolved, and then corresponds to the `id` filter on `creators.list`. Syncs started by `creator_vetting` are listed here too; a vetting reports its own sync as `sync_job_id`.

Calls GET /api/v1/creator_sync/ (creator_sync.list).

func (*CreatorVettingResource) ContentStatistics ¶

func (r *CreatorVettingResource) ContentStatistics(ctx context.Context, params *CreatorVettingContentStatisticsParams) (*ContentStatistics, error)

ContentStatistics returns aggregate totals (post count, views, engagement, earned media value, and unique creators) over the content tied to a creator vetting. Requires `vetting_id` (a vetting `id` from `creator_vetting.list`) and returns the same totals shape as `content.statistics`.

Calls GET /api/v1/creator/vetting/contents/statistics/ (creator_vetting.content_statistics).

func (*CreatorVettingResource) Contents ¶

func (r *CreatorVettingResource) Contents(ctx context.Context, params *CreatorVettingContentsParams) (*Page[Content], error)

Contents returns the content tied to a creator vetting, in the standard content shape. Use it to inspect the specific posts behind a vetting. Requires `vetting_id` (a vetting `id` from `creator_vetting.list`). Brand-scoped fields (`is_owned`, `is_tagged`, `net_promoter_score`, ...) are `null` in this response.

Calls GET /api/v1/creator/vetting/contents/ (creator_vetting.contents).

func (*CreatorVettingResource) Create ¶

func (r *CreatorVettingResource) Create(ctx context.Context, body CreatorVettingCreateJSONRequestBody) (*CreatorVetting, error)

Create vets a creator identified by `profile_url`, retrieving the profile and scoring its safety and brand fit. Runs complete asynchronously, so this method returns immediately with the created vetting. The vetting analyzes up to 150 of the creator's posts per connection type, or the limit configured for your workspace. The created vetting is returned as the single item in `results`. Take its `id` and poll `creator_vetting.list` until a run reports `COMPLETED`. A vetting can take an hour or more to complete, so prefer the `creator_vetting.completed` webhook over frequent polling, which can trigger `RATE_LIMIT_EXCEEDED`. Once a run is complete, retrieve the payload from `creator_vetting.results`, passing `vetting_id=<id>`.

Calls POST /api/v1/creator/vetting/ (creator_vetting.create).

func (*CreatorVettingResource) List ¶

func (r *CreatorVettingResource) List(ctx context.Context, params *CreatorVettingListParams) (*Page[CreatorVetting], error)

List returns creator vettings ordered newest first, each with its analysis runs and their current `status`. Use it to discover vettings and monitor run progress without retrieving the full result payload. A vetting `id` corresponds to the `vetting_id` parameter on `creator_vetting.results` and `creator_vetting.contents`, and each run's `id` corresponds to the `id` parameter on `creator_vetting.results`. The run `result` download is not included in this response; retrieve it from `creator_vetting.results` once a run reports `COMPLETED`. Possible statuses are `IN_PROGRESS`, `COMPLETED`, `EMPTY_RESULT`, and `FAILED`. Supply `creator_id` to filter to a single creator, or `id` to return a single vetting.

Calls GET /api/v1/creator/vetting/ (creator_vetting.list).

func (*CreatorVettingResource) Results ¶

func (r *CreatorVettingResource) Results(ctx context.Context, params *CreatorVettingResultsParams) (*Page[CreatorVettingResult], error)

Results returns the `result` for each run: a signed, time-limited download of the vetting analysis payload. Call this method after a run reaches `COMPLETED`; for earlier statuses the row is returned with a `null` `result`. Supply `vetting_id` (the vetting `id` from `creator_vetting.list`) to return every run of that vetting, or `id` (a single run's `id`) to return one run. One of the two is required. A malformed identifier returns `INVALID_ID`; omitting both returns `VALIDATION_ERROR`. **Disclosures.** When the vetting requested `DISCLOSURE`, the payload's `insight_json.disclosures` holds one entry per analyzed video: its `content_id` and a `result`. The `result` lists `evidence` items, each with the `source` it was found in (`frame` for on-screen text, `audio` for the speech transcription, `title`, `caption` or `metadata`), a `kind` (`sponsorship`, `affiliate`, `gifted` or `relationship` for a commercial relationship; `terms` or `risk` for offer conditions and warnings), the quoted `text` and, where known, `time_seconds`. It also gives each source a `channels` status: `present`, `absent` or `unknown` (not checked). Disclosures are not counted as violations. Limits: only videos up to 10 minutes are checked; on-screen text is read from sampled frames, so text shown only briefly can be missed; videos ZelfAI analyzed before the request are not re-analyzed for disclosures. An empty `evidence` list does not confirm that a video has no disclosure. Detection reports what was stated; it does not assess legal compliance.

Calls GET /api/v1/creator/vetting/results/ (creator_vetting.results).

func (*CreatorsResource) List ¶

func (r *CreatorsResource) List(ctx context.Context, params *CreatorsListParams) (*Page[Creator], error)

List returns creators across the platforms Zelf supports. At least one of `id`, `username`, or `email` must be supplied to scope the search. Results can be ordered with `order_by` (`follower_count`, `id`). The `id` of each creator corresponds to the `creator_id` filter on `creator_vetting.list`. Requests that supply none of the required filters return `INVALID_ID`.

Calls GET /api/v1/creator/ (creators.list).

func (*DetectionResource) Create ¶

func (r *DetectionResource) Create(ctx context.Context, body DetectionCreateJSONRequestBody) (*Detection, error)

Create detects a list of brands in one video. Zelf Detection reads the whole video and finds each scene where a brand is identifiable: its logo or name is visible (on a product, on packaging or in on-screen text) or the brand is named out loud. Every appearance (placement) comes back with its timestamp, what was detected and how confident the detection is. Send the brands in `context.hints.brands`. Identify the video with `content_id` (a video already in Zelf) or `content_url` (a link to any supported video). Sending both, or neither, returns `VALIDATION_ERROR`. A `content_url` that is not in Zelf yet is added first, which makes the detection take longer. **Limits** - One video per request, up to 90 minutes. YouTube, TikTok and Instagram videos. Photo posts are not supported. - A product with no visible logo or name, and no spoken mention, is not detected. - `content_url`: the full video link, not a short link (`vm.tiktok.com`, `vt.tiktok.com`, `tiktok.com/t/`). Supported forms: `youtube.com/watch?v=<id>`, `youtu.be/<id>`, `youtube.com/shorts/<id>`, `tiktok.com/@<handle>/video/<id>`, `instagram.com/reel/<id>`, `/p/<id>`, `/tv/<id>`. - `context.hints.brands`: 1 to 200 brands. No two names that differ only by punctuation or digits. - `context.hints.brands[].name`: up to 60 characters. - `context.hints.brands[].identifiers`: 2 to 10, each 2 to 200 characters, including the brand name. - `context.hints.brands[].negatives`: optional, up to 12, each up to 200 characters. A request that breaks a rule returns `VALIDATION_ERROR` for the first rule it breaks. `error.details.field` names the field, for example `context.hints.brands[3].identifiers`, and `error.details.code` is one of `INVALID_REQUEST`, `NO_BRANDS`, `TOO_MANY_BRANDS`, `INVALID_BRAND`, `IDENTIFIER_COUNT`, `IDENTIFIER_TOO_SHORT`, `UNSUPPORTED_URL`, `SHORT_LINK`, `PHOTO_POST` or `VIDEO_TOO_LONG`. Detection is asynchronous. This method returns immediately with the detection at `status: SCHEDULED`. Poll `detection.get` until `status` is `SUCCESS` or `FAILED`; both are final.

Calls POST /api/v1/detection/ (detection.create).

func (*DetectionResource) Get ¶

func (r *DetectionResource) Get(ctx context.Context, id string) (*Detection, error)

Get retrieve one detection by `id`, the value returned by `detection.create`. Poll it until `status` is `SUCCESS` or `FAILED`; both are final. `result` is `null` until then. On `FAILED`, `result` carries the counts and `brands: []`. **Reading `result`** - `brands`: one entry per requested brand, in request order. `found: false` means the brand was searched for and does not appear in the video. - `timestamp`: `mm:ss-mm:ss`, or `mm:ss` for a single moment. Past an hour the minutes keep counting (`69:23-69:25`). - `modality`: `Visual` (logo or product on screen), `Text` (brand name written on screen) or `Audio` (brand name spoken). - `confidence`: `confirmed` means the placement passed a final check against the video's frames; `review` means it was detected but did not pass that final frame check. `Audio` placements are always `review`, because a spoken mention has no frames to check. On `Visual` and `Text` placements, `review` means the final frame check did not confirm the placement. - `video_url_at_timestamp`: YouTube only, opens the video 5 seconds before the placement. `null` on TikTok and Instagram.

Calls GET /api/v1/detection/{id}/ (detection.get).

func (*DetectionResource) List ¶

func (r *DetectionResource) List(ctx context.Context, params *DetectionListParams) (*Page[Detection], error)

List lists detections, newest first. Each detection has its current `status` and, once finished, its placements in `result`. Possible statuses are `SCHEDULED`, `IN_PROGRESS`, `SUCCESS` and `FAILED`. `SUCCESS` and `FAILED` are final.

Calls GET /api/v1/detection/ (detection.list).

func (*Page[T]) All ¶

func (p *Page[T]) All(ctx context.Context, opts ...PageOption) iter.Seq2[T, error]

All ranges over the remaining items, yielding the error that ended the walk as the second value. Stop early by breaking out of the loop.

for item, err := range page.All(ctx, zelf.MaxItems(100)) {
    if err != nil { return err }
    ...
}

func (*Page[T]) AppliedFilters ¶

func (p *Page[T]) AppliedFilters(into any) error

AppliedFilters decodes the effective filters the API reports back, which explains an empty result set.

func (*Page[T]) AutoPaging ¶

func (p *Page[T]) AutoPaging(ctx context.Context, visit func(item T) error, opts ...PageOption) error

AutoPaging walks the remaining pages and calls visit for each item. Returning an error from visit stops the walk and surfaces that error. MaxPages and MaxItems bound how far it goes.

func (*Page[T]) HasNext ¶

func (p *Page[T]) HasNext() bool

HasNext reports whether another page is available.

func (*Page[T]) NextPage ¶

func (p *Page[T]) NextPage(ctx context.Context) (*Page[T], error)

NextPage fetches the page after this one, or returns nil when there is none.

func (*SubBrandsResource) Create ¶

func (r *SubBrandsResource) Create(ctx context.Context, body SubBrandsCreateJSONRequestBody) (*Brand, error)

Create creates a sub-brand under the workspace brand. A sub-brand tracks a competitor (`COMPETITIVE`) or a content theme (`THEME`) separately. A brand may have at most 64 sub-brands; requests beyond this limit are rejected. The new brand's `id` is the value to supply as `brand_id` elsewhere.

Calls POST /api/v1/brands/ (sub_brands.create).

func (*UsageResource) Retrieve ¶

func (r *UsageResource) Retrieve(ctx context.Context) (*Usage, error)

Retrieve live consumption for your brand, per group and per window. Both sections come back however you call: `api` groups count requests made with an API key, `mcp` groups count the ones an AI client makes, and the two never share a counter. `authenticated_as` says which of them the current credentials spend. A window appears only when a limit is configured for it, so a brand with no monthly limit has no monthly row. Ask an administrator to set one and it appears here with no further work. `reset_in` counts down to the end of the current window, which starts on its first request rather than on the clock. Reading this consumes no quota.

Calls GET /api/v1/usage/ (usage.retrieve).

func (*WebhooksResource) CreateSecret ¶

func (r *WebhooksResource) CreateSecret(ctx context.Context, body WebhooksCreateSecretJSONRequestBody) (*WebhookSecretCreated, error)

CreateSecret creates a signing secret for the brand. The full `secret` is returned only once.

Calls POST /api/v1/webhooks/secrets/ (webhooks.create_secret).

func (*WebhooksResource) CreateSubscription ¶

func (r *WebhooksResource) CreateSubscription(ctx context.Context, body WebhooksCreateSubscriptionJSONRequestBody) (*WebhookSubscriptionCreated, error)

CreateSubscription creates a webhook subscription for your brand. The full signing `secret` is returned only once, in this response. A brand may hold at most one `event` subscription.

Calls POST /api/v1/webhooks/subscriptions/ (webhooks.create_subscription).

func (*WebhooksResource) DeleteSecret ¶

func (r *WebhooksResource) DeleteSecret(ctx context.Context, secretId string) (*WebhookDeleteAcknowledgement, error)

DeleteSecret deactivates a secret. The default secret, or one still linked to a subscription, cannot be deleted.

Calls DELETE /api/v1/webhooks/secrets/{secret_id}/ (webhooks.delete_secret).

func (*WebhooksResource) DeleteSubscription ¶

func (r *WebhooksResource) DeleteSubscription(ctx context.Context, subscriptionId string) (*WebhookDeleteAcknowledgement, error)

DeleteSubscription deletes a subscription. This is destructive: the subscription stops receiving deliveries.

Calls DELETE /api/v1/webhooks/subscriptions/{subscription_id}/ (webhooks.delete_subscription).

func (*WebhooksResource) GetDelivery ¶

func (r *WebhooksResource) GetDelivery(ctx context.Context, deliveryId string) (*WebhookDelivery, error)

GetDelivery returns a single delivery attempt.

Calls GET /api/v1/webhooks/deliveries/{delivery_id}/ (webhooks.get_delivery).

func (*WebhooksResource) GetSecret ¶

func (r *WebhooksResource) GetSecret(ctx context.Context, secretId string) (*WebhookSecret, error)

GetSecret returns a single secret.

Calls GET /api/v1/webhooks/secrets/{secret_id}/ (webhooks.get_secret).

func (*WebhooksResource) GetSubscription ¶

func (r *WebhooksResource) GetSubscription(ctx context.Context, subscriptionId string) (*WebhookSubscription, error)

GetSubscription returns a single subscription.

Calls GET /api/v1/webhooks/subscriptions/{subscription_id}/ (webhooks.get_subscription).

func (*WebhooksResource) ListDeliveries ¶

func (r *WebhooksResource) ListDeliveries(ctx context.Context, params *WebhooksListDeliveriesParams) (*Page[WebhookDelivery], error)

ListDeliveries lists webhook delivery attempts for the brand, newest first. Filter by `subscription` (masked id), `state`, and a `created_after` / `created_before` window.

Calls GET /api/v1/webhooks/deliveries/ (webhooks.list_deliveries).

func (*WebhooksResource) ListEvents ¶

func (r *WebhooksResource) ListEvents(ctx context.Context) ([]WebhookAvailableEvent, error)

ListEvents lists the event types an event subscription can listen for.

Calls GET /api/v1/webhooks/events/ (webhooks.list_events).

func (*WebhooksResource) ListSecrets ¶

func (r *WebhooksResource) ListSecrets(ctx context.Context, params *WebhooksListSecretsParams) (*Page[WebhookSecret], error)

ListSecrets lists the brand's active secrets.

Calls GET /api/v1/webhooks/secrets/ (webhooks.list_secrets).

func (*WebhooksResource) ListSubscriptions ¶

func (r *WebhooksResource) ListSubscriptions(ctx context.Context, params *WebhooksListSubscriptionsParams) (*Page[WebhookSubscription], error)

ListSubscriptions returns the webhook subscriptions owned by your brand, newest first.

Calls GET /api/v1/webhooks/subscriptions/ (webhooks.list_subscriptions).

func (*WebhooksResource) RotateSubscriptionSecret ¶

func (r *WebhooksResource) RotateSubscriptionSecret(ctx context.Context, subscriptionId string) (*WebhookSubscriptionCreated, error)

RotateSubscriptionSecret mints a new signing secret for the subscription and returns the full `secret` once. Deliveries after this use the new secret.

Calls POST /api/v1/webhooks/subscriptions/{subscription_id}/rotate_secret/ (webhooks.rotate_subscription_secret).

func (*WebhooksResource) SendTest ¶

func (r *WebhooksResource) SendTest(ctx context.Context, subscriptionId string) error

SendTest queues a test event to the subscription's URL so you can verify signing and parsing. Rate limited to 12 per hour per subscription. A disabled subscription is rejected.

Calls POST /api/v1/webhooks/subscriptions/{subscription_id}/send_test/ (webhooks.send_test).

func (*WebhooksResource) SetDefaultSecret ¶

func (r *WebhooksResource) SetDefaultSecret(ctx context.Context, secretId string) (*WebhookSecret, error)

SetDefaultSecret marks a secret as the brand's default for its kind.

Calls POST /api/v1/webhooks/secrets/{secret_id}/set_default/ (webhooks.set_default_secret).

func (*WebhooksResource) UpdateSubscription ¶

func (r *WebhooksResource) UpdateSubscription(ctx context.Context, subscriptionId string, body WebhooksUpdateSubscriptionJSONRequestBody) (*WebhookSubscription, error)

UpdateSubscription partially updates a subscription's `url`, `custom_headers`, `resource_filters`, `interval_hours`, `max_items`, or `enabled`. `kind`, `resource`, and `event_types` are immutable after create.

Calls PATCH /api/v1/webhooks/subscriptions/{subscription_id}/ (webhooks.update_subscription).