How to use AND, OR and NOT in search#

The APITube News API has a boolean search language behind one parameter: query. Send it to /v1/news/everything and you can join keywords with AND, offer alternatives with OR, and drop terms with NOT (or the - prefix), grouping any of them with parentheses. A bare word searches the article headline by default, so query=bitcoin AND ethereum finds headlines that contain both words.

curl "https://api.apitube.io/v1/news/everything?query=bitcoin AND ethereum&api_key=YOUR_API_KEY"

You can send the key as a header (X-API-Key: YOUR_API_KEY) instead of the api_key parameter. In a real request, URL-encode the query value — spaces, parentheses and quotes must be percent-encoded. The boolean language is opt-in: it only runs when you pass query=. Leave it out and your existing flat filters (title=, language.code=, and the rest) work exactly as before.

What does the query parameter do?#

The query parameter adds boolean logic on top of the same fields the flat filters already cover. Operator precedence is NOT first, then AND, then OR, and parentheses override that order. A bare term with no field prefix targets the headline, which means query=tesla is the same as query=title:tesla. Everything you build with query is combined with any flat parameters in the same request using AND, so you can mix both styles:

curl "https://api.apitube.io/v1/news/everything?read_time.min=2&query=title:bitcoin&api_key=YOUR_API_KEY"

How to combine keywords with AND#

Put AND between two conditions to require both. A plain space between terms means the same thing — an implicit AND — so query=bitcoin ethereum and query=bitcoin AND ethereum are identical. Both headline words must be present for an article to match:

curl "https://api.apitube.io/v1/news/everything?query=tesla AND recall&api_key=YOUR_API_KEY"

How to match either keyword with OR#

Use OR to accept any of several terms. When the words target the same field, scope them once and list the alternatives in parentheses — title:(tesla OR ford) matches a headline containing either name:

curl "https://api.apitube.io/v1/news/everything?query=title:(tesla OR ford)&api_key=YOUR_API_KEY"

Because AND binds tighter than OR, write (a OR b) AND c with explicit parentheses whenever you want the alternation evaluated first.

How to exclude keywords with NOT#

NOT removes anything that matches the condition after it. The - prefix is a shorthand for the same thing, so NOT lawsuit and -lawsuit behave alike. In a flat chain, NOT negates only the operand directly after it — query=tesla AND NOT lawsuit AND ford keeps Tesla-and-Ford headlines while dropping the ones that mention a lawsuit:

curl "https://api.apitube.io/v1/news/everything?query=tesla AND NOT lawsuit&api_key=YOUR_API_KEY"

NOT works on every field, not just the headline, which makes it the general replacement for the ignore.* parameters: NOT source.country.code:ru does the same job as ignore.source.country.code=ru. For the dedicated exclusion parameters, see How to exclude keywords or sources from news.

How to group conditions with parentheses#

Parentheses set evaluation order and let a NOT apply to a whole group instead of a single term. query=tesla AND NOT (recall OR lawsuit) keeps Tesla headlines but removes any that mention a recall or a lawsuit:

curl "https://api.apitube.io/v1/news/everything?query=tesla AND NOT (recall OR lawsuit)&api_key=YOUR_API_KEY"

You can nest groups up to 10 levels deep and use up to 64 conditions in one query, with a maximum query length of 4000 characters. Crossing any of those limits returns HTTP 400 with error ER0703.

How to run boolean logic across other fields#

Field names in query are the exact names of the flat parameters, so the boolean language reaches the whole filter set — language, source, category, date, media and more. This pulls English-language headlines about Tesla or Ford, but excludes Russian publishers:

curl "https://api.apitube.io/v1/news/everything?query=title:(tesla OR ford) AND language.code:en AND NOT source.country.code:ru&api_key=YOUR_API_KEY"

When a value contains a special character — a colon, space or parenthesis — wrap it in double quotes, for example category.id:"medtop:04000000". To filter by language on its own, see How to filter news by language. The full field reference lives on the official News API parameter docs.

What operators are not supported#

The boolean language deliberately leaves out a few Lucene-style operators because the underlying index can’t serve them. Fuzzy matching (term~2), wildcards (ter*, te?t), boosting (term^3) and regular expressions all return HTTP 400 with error ER0704. There is also no full-text search over the article body — bare terms always match the headline. For partial-title matching, use title.starts_with, title.ends_with or title.pattern instead of a wildcard.

Common Questions#

• Does a bare keyword search the article body?
• Is a space the same as AND or OR?
• Can I still use my flat filters with query?
• Why does my fuzzy or wildcard query fail?

Does a bare keyword search the article body?#

No. A term with no field prefix targets the headline only, so query=inflation is shorthand for query=title:inflation. The boolean language has no full-text search over the article body; the index only holds the title. If you need partial matches within the headline, use title.starts_with, title.ends_with or title.pattern.

Is a space the same as AND or OR?#

A space between two conditions is an implicit AND, not OR. query=tesla ford requires both words in the headline, exactly like query=tesla AND ford. To accept either word, you must write OR explicitly — query=title:(tesla OR ford).

Can I still use my flat filters with query?#

Yes. The query parameter is added to the request as a single condition joined to your flat parameters with AND. You can send read_time.min=2&query=title:bitcoin together, and both apply. Without query=, nothing changes and the flat filters behave exactly as they always have.

Why does my fuzzy or wildcard query fail?#

Fuzzy matching (~), wildcards (*, ?), boosting (^) and regex are not supported and return HTTP 400 with error ER0704. An unknown field name returns ER0702, and a syntax error such as an unclosed parenthesis returns ER0701. Check that every field name matches a real parameter and that your parentheses and quotes are balanced.