README

Introduction

Use the Numeno Article Recommender API to receive a curated selection of articles from across the web.

See below for the steps to creating a Feed, as well as an introduction to the top-level concepts making up the Article Recommender API.

Steps to creating a Feed

1. Create a Feed - createFeed
2. Create a number of Stream queries associated with the Feed - createStream
3. Pull from the Feed as the Feed refreshes - getArticlesInFeed
4. Use those Article IDs to look up metadata for the Articles -getArticleById
5. Visit the Article links and render to your server DB or client app.

Sources, Articles and Topics

A Source is a place where Articles come from, typically a website, a blog, or a knowledgebase endpoint. Sources can be queried for activity via the getSources endpoint. Beyond the Sources Numeno regaularly indexes, additional Sources can be associated with Stream queries, and Sources can be allowlist/denylist'd.

Articles are the documents produced by Sources, typically pages from a blogpost or website, articles from a news source, or posts from a social platform or company intranet. See the getArticles endpoint.

Topics - Numeno has millions of Topics that it associates with Articles when they are sourced. Topics are used in Stream queries, which themselves are composed to create Feeds. Get topics via the getTopics endpoint.

Feeds

A Feed is a collection of Streams. Feeds are configured to refresh on a regular schedule. No new Articles are published to a Feed except when it's refreshed. Feeds can be refreshed manually if the API Key Scopes allow.

You can ask for Articles chronologically or by decreasing score. You can also limit Articles to a date-range, meaning that you can produce Feeds from historical content.

Interact with Feeds via the createFeed endpoint.

Streams

Think of a Stream as a search query with a "volume control knob". It's a collection of Topics that you're interested and a collection of Sources you'd explicitly like to include or exclude. Streams are associated with a Feed, and a collection of Streams produce the sequence of Articles that appear when a Feed is refreshed.

The "volume control knob" on a Stream is a way to decide how many of the search results from the Stream query are included in the Feed. Our searches are "soft", and with a such a rich Article x Topic space to draw on, the "volume control" allows you to put a cuttoff on what you'd like included.

Streams are a nested resource of createFeed - get started by explorting createStream.

For more information, please visit https://numeno.ai/.

Installation & Usage

Requirements

PHP 7.4 and later.

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "minimum-stability": "dev",
  "require": {
    "numeno/api-art-rec": "dev-main"
  }
}

Then run composer install

Getting Started

Please follow the installation procedure and then run the following:

<?php
require_once(__DIR__ . '/vendor/autoload.php');



// Configure API key authorization: ApiKeyAuth
$config = NumenoArtRec\Configuration::getDefaultConfiguration()->setApiKey('X-Numeno-Key', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = NumenoArtRec\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-Numeno-Key', 'Bearer');


$apiInstance = new NumenoArtRec\Api\DefaultApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$feed_new = new \NumenoArtRec\Model\FeedNew(); // \NumenoArtRec\Model\FeedNew

try {
    $result = $apiInstance->createFeed($feed_new);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling DefaultApi->createFeed: ', $e->getMessage(), PHP_EOL;
}

API Endpoints

All URIs are relative to https://api.numeno.ai/art-rec

Models

• Article
• ArticleShort
• ArticleShortList
• ErrorDetail
• ErrorResponse
• Feed
• FeedArticle
• FeedArticleList
• FeedFull
• FeedList
• FeedNew
• FeedSchedule
• FeedTuner
• FeedUpdate
• HealthCheck
• Query
• QueryBase
• QueryOrContinuation
• QuerySources
• QueryTopics
• QueryTopicsItems
• Scopes
• SearchArticle
• SearchArticleList
• SearchContinuation
• SearchQuery
• SourceAndCount
• SourceAndCountList
• Stream
• StreamList
• StreamNew
• StreamQuery
• StreamUpdate
• TopicAndWeight
• TopicAndWeightList
• VolumeControl

Authorization

Authentication schemes defined for the API:

ApiKeyAuth

• Type: API key
• API key parameter name: X-Numeno-Key
• Location: HTTP header

Author

support@numeno.ai

About this package

This PHP package is automatically generated by the OpenAPI Generator project:

• API version: 1.0.0
  • Package version: 0.0.6
  • Generator version: 7.10.0
• Build package: org.openapitools.codegen.languages.PhpClientCodegen