Article Meta¶

Article metadata is defined using meta_type keys paired with category values. Tags appear in article metadata[] and power meta filters on every endpoint that filters by article metadata.

Meta types¶

Meta types can be defined in Agate, so the best place to start is often the discovery endpoints. Several preset metadata values are commonly extracted in Agate flows:

`meta_type`	Meaning	Reference
`information_needs`	Critical information needs the story helps readers meet	Critical Information Need
`format`	Story type or structural form	Format
`geographic_scope`	Primary geographic scope of impact	Scope
`subject`	Concrete primary subject (the central thing the story covers)	Subject
`temporal_orientation`	How the story relates to time	Timeframe
`topic`	Broad topic areas (what the story is about)	Topic
`user_need`	Dominant audience need the story serves	User Need

Querying with `meta`¶

Use meta for advanced metadata filtering on any endpoint that filters by article metadata. Provide one clause per value; all clauses are combined with AND.

Each meta value is one clause:

Form	Meaning
`type`	Article has at least one tag of this metadata type (any category)
`type:category`	Article has this exact type + category
`type:cat1\\|cat2\\|cat3`	Article has this type with any one of the listed categories (OR within the type)
`!type`	Article must not have any tag of this type
`!type:category`	Article must not have this exact type + category

Prefix with ! to negate. The | character means OR only within a single clause — there is no cross-type OR.

To require all of several categories of the same type, repeat the type:

meta=topic:pro_sports&meta=topic:analysis

Unknown types or categories match nothing (no error).

Transport¶

How you send meta depends on the endpoint:

Transport	Endpoints	Example
GET — repeat `meta` as a query parameter	List and search articles, Geographic search, Geo cells coverage, Geo cell article drill-down, List and search mentions	`?meta=topic:pro_sports&meta=!format:opinion`
POST — pass `meta` as a JSON string array	Semantic search, Geo cells batch query	`"meta": ["topic:pro_sports", "!format:opinion"]`

On mention and geo routes, meta filters apply to the article that contains each mention or location — not to mention tags themselves.

Worked example¶

Factual game previews and recaps — pro sports coverage of a specific contest, without explainer or analysis pieces:

?meta=topic:pro_sports
 &meta=subject:sports_contest
 &meta=!format:explainer_analysis

The same clauses in a POST JSON body:

{
  "meta": ["topic:pro_sports", "subject:sports_contest", "!format:explainer_analysis"]
}

URL-encode | as %7C in GET query strings.

Limits¶

Max 25 meta clauses per request
Max 50 categories per clause (the part after :)

Malformed clauses (empty type, trailing :, empty category in a list) return 400.

Use meta as the only article-metadata filter input. Compatibility query parameters such as meta_type, meta_category, exclude_meta_type, and exclude_meta_category are not part of the v1 contract. For article fields, use external_source rather than source; section is not a supported public filter.

Discover values in your project¶

Projects may not use every category. Discover values with Article facets or the metadata types routes:

curl "https://api.{organization_slug}.backfield.news/public/v1/projects/general/articles/metadata/types/topic/values" \
  -H "Authorization: Bearer bfk_your_project_api_key"

Discovery	Filter clause
`…/metadata/types/information_needs/values`	`meta=information_needs:…` — see Critical Information Need
Article facets `format_categories`	`meta=format:…` — see Format
`…/metadata/types/geographic_scope/values`	`meta=geographic_scope:…` — see Scope
Article facets `topic_categories` or `…/metadata/types/topic/values`	`meta=topic:…` — see Topic
Article facets `subject_categories` or `…/metadata/types/subject/values`	`meta=subject:…` — see Subject
`…/metadata/types/temporal_orientation/values`	`meta=temporal_orientation:…` — see Timeframe
`…/metadata/types/user_need/values`	`meta=user_need:…` — see User Need

Also available:

GET …/articles/metadata/types — metadata types present in the project
GET …/articles/metadata/types/{meta_type}/values — categories for one type