NumenoAPI-php

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

Create a Feed - createFeed
Pull from the Feed as the Feed refreshes - getArticlesInFeed
Use those Article IDs to look up metadata for the Articles -getArticleById
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 regularly indexes, additional Sources can be associated with Feed 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 Feed queries, which themselves are composed to create Feeds. Get topics via the getTopics endpoint.

Feeds

Feeds can be of different types:

query - a Feed that is generated by a search query and refreshes on a regular schedule. In addition, Query Feed have a "volume control knob" that allows you to control how many of the search results are included in the Feed. It's a collection of Topics that you're interested and a collection of Sources you'd explicitly like to include or exclude. No new Articles are published to a Feed except when it's refreshed. Query Feeds can be refreshed manually if the API Key Scopes allow.
mix - a Feed that is generated by a mix of ofther Feeds. Mix Feeds refresh as soon as one of their subfeed refreshes.
external - a Feed that is generated by an external source, such as an Agent from the Persona API. External Feeds refresh when new Articles are added to them.

You can ask for Feed 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.

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

Installation & Usage

Requirements

PHP 7.4 and later. Should also work with PHP 8.0.

Composer

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

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/GIT_USER_ID/GIT_REPO_ID.git"
    }
  ],
  "require": {
    "GIT_USER_ID/GIT_REPO_ID": "*@dev"
  }
}

Then run composer install

Manual Installation

Download the files and include autoload.php:

<?php
require_once('/path/to/NumenoAPI-php/vendor/autoload.php');

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\NumenoArtRecApi(
    // 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_id = 'feed_id_example'; // string | The unique identifier of the Feed.
$article_in_feed_new_list = new \NumenoArtRec\Model\ArticleInFeedNewList(); // \NumenoArtRec\Model\ArticleInFeedNewList

try {
    $apiInstance->addArticlesToFeed($feed_id, $article_in_feed_new_list);
} catch (Exception $e) {
    echo 'Exception when calling NumenoArtRecApi->addArticlesToFeed: ', $e->getMessage(), PHP_EOL;
}

API Endpoints

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

Class	Method	HTTP request	Description
NumenoArtRecApi	addArticlesToFeed	POST /v1/feeds/{feedId}/articles	Add articles to an external Feed
NumenoArtRecApi	createFeed	POST /v1/feeds	Create a new Feed
NumenoArtRecApi	deleteFeed	DELETE /v1/feeds/{id}	Delete a Feed by ID
NumenoArtRecApi	getArticleById	GET /v1/articles/{id}	Get a specific Article by ID
NumenoArtRecApi	getArticles	GET /v1/articles	Get a list of all Articles
NumenoArtRecApi	getArticlesInFeed	GET /v1/feeds/{feedId}/articles	Get a list of all Articles in a Feed
NumenoArtRecApi	getFeedById	GET /v1/feeds/{id}	Get a specific Feed by ID
NumenoArtRecApi	getFeedSubscriptionById	GET /v1/feeds/{feedId}/subscriptions/{id}	Get a Subscription
NumenoArtRecApi	getFeedSubscriptions	GET /v1/feeds/{feedId}/subscriptions	Get all Subscriptions for a Feed
NumenoArtRecApi	getFeeds	GET /v1/feeds	Get a list of all Feeds
NumenoArtRecApi	getScopes	GET /v1/scopes	Get the Scopes for this API
NumenoArtRecApi	getSources	GET /v1/sources	Get Sources and their Articles
NumenoArtRecApi	getTopics	GET /v1/topics	Get a list of all Topics
NumenoArtRecApi	healthCheck	GET /health	Check the health of the API
NumenoArtRecApi	refreshFeed	POST /v1/feeds/{feedId}/refresh	Force a Feed to refresh
NumenoArtRecApi	searchArticles	POST /v1/articles/search	Search for Articles
NumenoArtRecApi	subscribeToFeed	POST /v1/feeds/{feedId}/subscriptions	Subscribe to a Feed
NumenoArtRecApi	unsubscribeFromFeed	DELETE /v1/feeds/{feedId}/subscriptions/{id}	Unsubscribe from a Feed
NumenoArtRecApi	updateFeed	PUT /v1/feeds/{id}	Update a Feed by ID

Models

Authorization

Authentication schemes defined for the API:

ApiKeyAuth

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

Tests

To run the tests, use:

composer install
vendor/bin/phpunit

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.8
- Generator version: 7.10.0
Build package: org.openapitools.codegen.languages.PhpClientCodegen

Introduction​

Steps to creating a Feed​

Sources, Articles and Topics​

Feeds​

Installation & Usage​

Requirements​

Composer​

Manual Installation​

Getting Started​

API Endpoints​

Models​

Authorization​

ApiKeyAuth​

Tests​

Author​

About this package​