Controller API

Service

POST /services

Create a new service.

Request Headers
  • Api-Key – for user authentication

Status Codes

http

POST /services HTTP/1.1
Host: controller.beta.pinecone.io
Accept: application/json
Content-Type: application/json
Api-Key: XXXX-XXXX-XXXX-XXXX

{
    "service": {
        "version": "pinecone/v1alpha1",
        "kind": "Service",
        "metadata": {
            "name": "movie-recommender-service"
        },
        "spec": {
            "functions": [
                {
                    "name": "engine",
                    "class": "pinecone.functions.engine.namespaced.NamespacedEngine",
                    "args": [
                        "--config",
                        "{\"metric\":\"cosine\",\"engine_type\":\"approximated\"}",
                        "--replicas",
                        "1",
                        "--shards",
                        "1",
                        "--name",
                        "engine"
                    ]
                },
                {
                    "name": "aggregator",
                    "class": "pinecone.functions.ranker.aggregator.Aggregator",
                    "args": [
                        "--config",
                        "{\"num_shards\":1}",
                        "--replicas",
                        "1",
                        "--shards",
                        "1",
                        "--name",
                        "aggregator"
                    ]
                }
            ],
            "paths": [
                {
                    "name": "read",
                    "steps": [
                        "engine",
                        "aggregator"
                    ]
                },
                {
                    "name": "write",
                    "steps": [
                        "engine",
                        "aggregator"
                    ]
                }
            ]
        }
    }
}

curl

curl -i -X POST https://controller.beta.pinecone.io/services -H 'Accept: application/json' -H 'Api-Key: XXXX-XXXX-XXXX-XXXX' -H 'Content-Type: application/json' --data-raw '{"service": {"kind": "Service", "metadata": {"name": "movie-recommender-service"}, "spec": {"functions": [{"name": "engine", "class": "pinecone.functions.engine.namespaced.NamespacedEngine", "args": ["--config", "{\"metric\":\"cosine\",\"engine_type\":\"approximated\"}", "--replicas", "1", "--shards", "1", "--name", "engine"]}, {"name": "aggregator", "class": "pinecone.functions.ranker.aggregator.Aggregator", "args": ["--config", "{\"num_shards\":1}", "--replicas", "1", "--shards", "1", "--name", "aggregator"]}], "paths": [{"name": "read", "steps": ["engine", "aggregator"]}, {"name": "write", "steps": ["engine", "aggregator"]}]}, "version": "pinecone/v1alpha1"}}'

wget

wget -S -O- https://controller.beta.pinecone.io/services --header='Accept: application/json' --header='Api-Key: XXXX-XXXX-XXXX-XXXX' --header='Content-Type: application/json' --post-data='{"service": {"kind": "Service", "metadata": {"name": "movie-recommender-service"}, "spec": {"functions": [{"name": "engine", "class": "pinecone.functions.engine.namespaced.NamespacedEngine", "args": ["--config", "{\"metric\":\"cosine\",\"engine_type\":\"approximated\"}", "--replicas", "1", "--shards", "1", "--name", "engine"]}, {"name": "aggregator", "class": "pinecone.functions.ranker.aggregator.Aggregator", "args": ["--config", "{\"num_shards\":1}", "--replicas", "1", "--shards", "1", "--name", "aggregator"]}], "paths": [{"name": "read", "steps": ["engine", "aggregator"]}, {"name": "write", "steps": ["engine", "aggregator"]}]}, "version": "pinecone/v1alpha1"}}'

python-requests

requests.post('https://controller.beta.pinecone.io/services', headers={'Accept': 'application/json', 'Api-Key': 'XXXX-XXXX-XXXX-XXXX', 'Content-Type': 'application/json'}, json={'service': {'kind': 'Service', 'metadata': {'name': 'movie-recommender-service'}, 'spec': {'functions': [{'name': 'engine', 'class': 'pinecone.functions.engine.namespaced.NamespacedEngine', 'args': ['--config', '{"metric":"cosine","engine_type":"approximated"}', '--replicas', '1', '--shards', '1', '--name', 'engine']}, {'name': 'aggregator', 'class': 'pinecone.functions.ranker.aggregator.Aggregator', 'args': ['--config', '{"num_shards":1}', '--replicas', '1', '--shards', '1', '--name', 'aggregator']}], 'paths': [{'name': 'read', 'steps': ['engine', 'aggregator']}, {'name': 'write', 'steps': ['engine', 'aggregator']}]}, 'version': 'pinecone/v1alpha1'}})

response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}
GET /services

List a user’s services.

Request Headers
  • Api-Key – for user authentication

Status Codes

http

GET /services HTTP/1.1
Host: controller.beta.pinecone.io
Api-Key: XXXX-XXXX-XXXX-XXXX

curl

curl -i https://controller.beta.pinecone.io/services -H 'Api-Key: XXXX-XXXX-XXXX-XXXX'

wget

wget -S -O- https://controller.beta.pinecone.io/services --header='Api-Key: XXXX-XXXX-XXXX-XXXX'

python-requests

requests.get('https://controller.beta.pinecone.io/services', headers={'Api-Key': 'XXXX-XXXX-XXXX-XXXX'})

response

HTTP/1.1 200 OK
Content-Type: application/json

[
    "movie-recommender-service-1",
    "movie-recommender-service-2"
]
GET /services/(service_name)

Get the configuration of a service.

Parameters
  • service_name – name of the service

Request Headers
  • Api-Key – for user authentication

Status Codes

http

GET /services/(service_name) HTTP/1.1
Host: controller.beta.pinecone.io
Api-Key: XXXX-XXXX-XXXX-XXXX

curl

curl -i 'https://controller.beta.pinecone.io/services/(service_name)' -H 'Api-Key: XXXX-XXXX-XXXX-XXXX'

wget

wget -S -O- 'https://controller.beta.pinecone.io/services/(service_name)' --header='Api-Key: XXXX-XXXX-XXXX-XXXX'

python-requests

requests.get('https://controller.beta.pinecone.io/services/(service_name)', headers={'Api-Key': 'XXXX-XXXX-XXXX-XXXX'})

response

HTTP/1.1 200 OK
Content-Type: application/json

{
        "version": "pinecone/v1alpha1",
        "kind": "Service",
        "metadata": {
            "name": "movie-recommender-service"
        },
        "spec": {
            "functions": [
                {
                    "name": "engine",
                    "class": "pinecone.functions.engine.namespaced.NamespacedEngine",
                    "args": [
                        "--config",
                        "{\"metric\":\"cosine\",\"engine_type\":\"approximated\"}",
                        "--replicas",
                        "1",
                        "--shards",
                        "1",
                        "--name",
                        "engine"
                    ]
                },
                {
                    "name": "aggregator",
                    "class": "pinecone.functions.ranker.aggregator.Aggregator",
                    "args": [
                        "--config",
                        "{\"num_shards\":1}",
                        "--replicas",
                        "1",
                        "--shards",
                        "1",
                        "--name",
                        "aggregator"
                    ]
                }
            ],
            "paths": [
                {
                    "name": "read",
                    "steps": [
                        "engine",
                        "aggregator"
                    ]
                },
                {
                    "name": "write",
                    "steps": [
                        "engine",
                        "aggregator"
                    ]
                }
            ]
        }
}
DELETE /services/(service_name)

Delete a service.

Parameters
  • service_name – name of the service

Request Headers
  • Api-Key – for user authentication

Status Codes

http

DELETE /services/(service_name) HTTP/1.1
Host: controller.pinecone.io
Api-Key: XXXX-XXXX-XXXX-XXXX

curl

curl -i -X DELETE 'https://controller.pinecone.io/services/(service_name)' -H 'Api-Key: XXXX-XXXX-XXXX-XXXX'

wget

wget -S -O- --method=DELETE 'https://controller.pinecone.io/services/(service_name)' --header='Api-Key: XXXX-XXXX-XXXX-XXXX'

python-requests

requests.delete('https://controller.pinecone.io/services/(service_name)', headers={'Api-Key': 'XXXX-XXXX-XXXX-XXXX'})

response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}
GET /services/(service_name)/status

Get the status of a service.

Parameters
  • service_name – name of the service

Request Headers
  • Api-Key – for user authentication

Status Codes

http

GET /services/(service_name)/status HTTP/1.1
Host: controller.beta.pinecone.io
Api-Key: XXXX-XXXX-XXXX-XXXX

curl

curl -i 'https://controller.beta.pinecone.io/services/(service_name)/status' -H 'Api-Key: XXXX-XXXX-XXXX-XXXX'

wget

wget -S -O- 'https://controller.beta.pinecone.io/services/(service_name)/status' --header='Api-Key: XXXX-XXXX-XXXX-XXXX'

python-requests

requests.get('https://controller.beta.pinecone.io/services/(service_name)/status', headers={'Api-Key': 'XXXX-XXXX-XXXX-XXXX'})

response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ready": false,
    "waiting": ["engine-0", "transformer-0"],
    "crashed": [],
    "host": null,
    "port": null
}

Router

The APIs for traffic routers work in the same way as the APIs for services. You only need to replace /services with /routers and service_name with router_name.

POST /routers

Create a new traffic router or update an existing traffic router. Note that JSON data structure for traffic routers requests differs from that of services’. Also see POST /services for more details.

http

POST /routers HTTP/1.1
Host: controller.beta.pinecone.io
Accept: application/json
Content-Type: application/json
Api-Key: XXXX-XXXX-XXXX-XXXX

{
    "router": {
        "version": "pinecone/v1alpha1",
        "kind": "TrafficRouter",
        "metadata": {
            "name": "movie-recommender-router"
        },
        "spec": {
            "active": "movie-recommender-service-v1",
            "services": [
                "movie-recommender-service-v1",
                "movie-recommender-service-v2"
            ]
        }
    }
}

curl

curl -i -X POST https://controller.beta.pinecone.io/routers -H 'Accept: application/json' -H 'Api-Key: XXXX-XXXX-XXXX-XXXX' -H 'Content-Type: application/json' --data-raw '{"router": {"kind": "TrafficRouter", "metadata": {"name": "movie-recommender-router"}, "spec": {"active": "movie-recommender-service-v1", "services": ["movie-recommender-service-v1", "movie-recommender-service-v2"]}, "version": "pinecone/v1alpha1"}}'

wget

wget -S -O- https://controller.beta.pinecone.io/routers --header='Accept: application/json' --header='Api-Key: XXXX-XXXX-XXXX-XXXX' --header='Content-Type: application/json' --post-data='{"router": {"kind": "TrafficRouter", "metadata": {"name": "movie-recommender-router"}, "spec": {"active": "movie-recommender-service-v1", "services": ["movie-recommender-service-v1", "movie-recommender-service-v2"]}, "version": "pinecone/v1alpha1"}}'

python-requests

requests.post('https://controller.beta.pinecone.io/routers', headers={'Accept': 'application/json', 'Api-Key': 'XXXX-XXXX-XXXX-XXXX', 'Content-Type': 'application/json'}, json={'router': {'kind': 'TrafficRouter', 'metadata': {'name': 'movie-recommender-router'}, 'spec': {'active': 'movie-recommender-service-v1', 'services': ['movie-recommender-service-v1', 'movie-recommender-service-v2']}, 'version': 'pinecone/v1alpha1'}})

response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}
GET /routers

List a user’s routers. See GET /services for details.

GET /routers/(router_name)

Get the configuration of a router. See GET /services/(service_name) for details.

DELETE /routers/(router_name)

Delete a router. See DELETE /services/(service_name) for details.

GET /routers/(router_name)/status

Get the status of a router. See GET /services/(service_name)/status for details.

Action

GET /actions/whoami

Get user information.

Request Headers
  • Api-Key – for user authentication

Status Codes

http

GET /actions/whoami HTTP/1.1
Host: controller.beta.pinecone.io
Api-Key: XXXX-XXXX-XXXX-XXXX

curl

curl -i https://controller.beta.pinecone.io/actions/whoami -H 'Api-Key: XXXX-XXXX-XXXX-XXXX'

wget

wget -S -O- https://controller.beta.pinecone.io/actions/whoami --header='Api-Key: XXXX-XXXX-XXXX-XXXX'

python-requests

requests.get('https://controller.beta.pinecone.io/actions/whoami', headers={'Api-Key': 'XXXX-XXXX-XXXX-XXXX'})

response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "user_label": "user_label",
    "user_name": "user_name",
    "project_name": "user_name"
}
GET /actions/version

Get the Pinecone controller version.

Request Headers
  • Api-Key – for user authentication

Status Codes

http

GET /actions/version HTTP/1.1
Host: controller.beta.pinecone.io
Api-Key: XXXX-XXXX-XXXX-XXXX

curl

curl -i https://controller.beta.pinecone.io/actions/version -H 'Api-Key: XXXX-XXXX-XXXX-XXXX'

wget

wget -S -O- https://controller.beta.pinecone.io/actions/version --header='Api-Key: XXXX-XXXX-XXXX-XXXX'

python-requests

requests.get('https://controller.beta.pinecone.io/actions/version', headers={'Api-Key': 'XXXX-XXXX-XXXX-XXXX'})

response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "version": "version"
}