openapi: 3.0.0 info: title: Portkey Analytics > Graphs Rerank API description: The Portkey REST API. Please see https://portkey.ai/docs/api-reference for more details. version: 2.0.0 termsOfService: https://portkey.ai/terms contact: name: Portkey Developer Forum url: https://portkey.wiki/community license: name: MIT url: https://github.com/Portkey-AI/portkey-openapi/blob/master/LICENSE servers: - url: https://api.portkey.ai/v1 description: Portkey API Public Endpoint security: - Portkey-Key: [] tags: - name: Rerank description: Rerank a list of documents based on their relevance to a query. Supported providers include Cohere, Voyage, Jina, Pinecone, Bedrock, and Azure AI. paths: /rerank: servers: - url: https://api.portkey.ai/v1 description: Portkey API Public Endpoint - url: SELF_HOSTED_GATEWAY_URL description: Self-Hosted Gateway URL post: operationId: createRerank tags: - Rerank summary: Rerank description: 'Reranks a list of documents based on their relevance to a query. This endpoint provides a unified interface to reranking models from multiple providers including Cohere, Voyage, Jina, Pinecone, Bedrock, and Azure AI. Reranking is useful for improving search results by scoring and sorting documents based on semantic relevance to a query, rather than just keyword matching. ' parameters: - $ref: '#/components/parameters/PortkeyTraceId' - $ref: '#/components/parameters/PortkeySpanId' - $ref: '#/components/parameters/PortkeyParentSpanId' - $ref: '#/components/parameters/PortkeySpanName' - $ref: '#/components/parameters/PortkeyMetadata' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRerankRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreateRerankResponse' security: - Portkey-Key: [] Virtual-Key: [] - Portkey-Key: [] Provider-Auth: [] Provider-Name: [] - Portkey-Key: [] Config: [] - Portkey-Key: [] Provider-Auth: [] Provider-Name: [] Custom-Host: [] x-code-samples: - lang: curl label: Default source: "curl https://api.portkey.ai/v1/rerank \\\n -H \"x-portkey-api-key: $PORTKEY_API_KEY\" \\\n -H \"x-portkey-virtual-key: $PORTKEY_PROVIDER_VIRTUAL_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"rerank-v3.5\",\n \"query\": \"What is the capital of France?\",\n \"documents\": [\n \"Paris is the capital of France.\",\n \"Berlin is the capital of Germany.\",\n \"Madrid is the capital of Spain.\"\n ],\n \"top_n\": 2\n }'\n" - lang: python label: Default source: "from portkey_ai import Portkey\n\nclient = Portkey(\n api_key = \"PORTKEY_API_KEY\",\n virtual_key = \"PROVIDER_VIRTUAL_KEY\"\n)\n\nresponse = client.post(\n \"/rerank\",\n model=\"rerank-v3.5\",\n query=\"What is the capital of France?\",\n documents=[\n \"Paris is the capital of France.\",\n \"Berlin is the capital of Germany.\",\n \"Madrid is the capital of Spain.\",\n ],\n top_n=2,\n)\n\nprint(response)\n" - lang: javascript label: Default source: "import Portkey from 'portkey-ai';\n\nconst client = new Portkey({\n apiKey: 'PORTKEY_API_KEY',\n virtualKey: 'PROVIDER_VIRTUAL_KEY'\n});\n\nasync function main() {\n const response = await client.post('/rerank', {\n model: 'rerank-v3.5',\n query: 'What is the capital of France?',\n documents: [\n 'Paris is the capital of France.',\n 'Berlin is the capital of Germany.',\n 'Madrid is the capital of Spain.'\n ],\n top_n: 2\n });\n\n console.log(response);\n}\n\nmain();\n" - lang: curl label: Self-Hosted source: "curl -X POST \"SELF_HOSTED_GATEWAY_URL/rerank\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-portkey-api-key: $PORTKEY_API_KEY\" \\\n -H \"x-portkey-virtual-key: $PORTKEY_PROVIDER_VIRTUAL_KEY\" \\\n -d '{\n \"model\": \"rerank-v3.5\",\n \"query\": \"What is the capital of France?\",\n \"documents\": [\n \"Paris is the capital of France.\",\n \"Berlin is the capital of Germany.\",\n \"Madrid is the capital of Spain.\"\n ],\n \"top_n\": 2\n }'\n" - lang: python label: Self-Hosted source: "from portkey_ai import Portkey\n\nclient = Portkey(\n api_key=\"PORTKEY_API_KEY\",\n virtual_key=\"PROVIDER_VIRTUAL_KEY\",\n base_url=\"SELF_HOSTED_GATEWAY_URL\"\n)\n\nresponse = client.post(\n \"/rerank\",\n model=\"rerank-v3.5\",\n query=\"What is the capital of France?\",\n documents=[\n \"Paris is the capital of France.\",\n \"Berlin is the capital of Germany.\",\n \"Madrid is the capital of Spain.\",\n ],\n top_n=2,\n)\n\nprint(response)\n" - lang: javascript label: Self-Hosted source: "import Portkey from 'portkey-ai';\n\nconst client = new Portkey({\n apiKey: 'PORTKEY_API_KEY',\n virtualKey: 'PROVIDER_VIRTUAL_KEY',\n baseURL: 'SELF_HOSTED_GATEWAY_URL'\n});\n\nasync function main() {\n const response = await client.post('/rerank', {\n model: 'rerank-v3.5',\n query: 'What is the capital of France?',\n documents: [\n 'Paris is the capital of France.',\n 'Berlin is the capital of Germany.',\n 'Madrid is the capital of Spain.'\n ],\n top_n: 2\n });\n\n console.log(response);\n}\n\nmain();\n" components: parameters: PortkeyTraceId: in: header name: x-portkey-trace-id schema: type: string description: An ID you can pass to refer to one or more requests later on. If not provided, Portkey generates a trace ID automatically for each request. [Docs](https://portkey.ai/docs/product/observability/traces) required: false PortkeySpanName: in: header name: x-portkey-span-name schema: type: string description: Name for the Span ID required: false PortkeyMetadata: in: header name: x-portkey-metadata schema: type: object description: Pass any arbitrary metadata along with your request required: false PortkeySpanId: in: header name: x-portkey-span-id schema: type: string description: An ID you can pass to refer to a span under a trace. required: false PortkeyParentSpanId: in: header name: x-portkey-parent-span-id schema: type: string description: Link a child span to a parent span required: false schemas: RerankResult: type: object description: A single reranked document result. properties: index: type: integer description: The index of the document in the original input array. example: 0 relevance_score: type: number format: float description: 'The relevance score of the document to the query. Higher scores indicate greater relevance. Score ranges vary by provider but are typically between 0 and 1. ' example: 0.98 document: type: object description: The original document text. Only present if `return_documents` is true. properties: text: type: string description: The text content of the document. additionalProperties: true required: - index - relevance_score RerankUsage: type: object description: Usage information for the rerank request. properties: search_units: type: integer description: 'The number of search units consumed by the request. Billing varies by provider. ' CreateRerankRequest: type: object description: 'Request body for reranking documents. The unified API supports multiple providers including Cohere, Voyage, Jina, Pinecone, Bedrock, and Azure AI. ' properties: model: description: 'ID of the model to use for reranking. Model availability depends on the provider: - **Cohere**: `rerank-v3.5`, `rerank-english-v3.0`, `rerank-multilingual-v3.0`, `rerank-english-v2.0`, `rerank-multilingual-v2.0` - **Voyage**: `rerank-2`, `rerank-2-lite` - **Jina**: `jina-reranker-v2-base-multilingual`, `jina-reranker-v1-base-en`, `jina-reranker-v1-turbo-en`, `jina-reranker-v1-tiny-en` - **Pinecone**: `bge-reranker-v2-m3`, `pinecone-rerank-v0` - **Bedrock**: Model ARN (e.g., `arn:aws:bedrock:us-west-2::foundation-model/cohere.rerank-v3-5:0`) - **Azure AI**: Cohere rerank deployments on Azure AI Inference; use the model name from your deployment, typically prefixed with `cohere.` (the gateway strips that prefix for the upstream request) ' type: string example: rerank-v3.5 query: description: The search query to compare against the documents. type: string example: What is the capital of France? documents: description: 'The list of documents to rerank. Each document can be a string or an object with a `text` field. The documents will be scored based on their relevance to the query. ' type: array items: $ref: '#/components/schemas/RerankDocument' minItems: 1 example: - Paris is the capital of France. - Berlin is the capital of Germany. - Madrid is the capital of Spain. top_n: description: 'The number of top results to return. If not specified, all documents are returned sorted by relevance. For Voyage, the gateway maps this field to the provider''s `top_k` parameter. ' type: integer minimum: 1 example: 3 return_documents: description: 'Whether to return the document text in the response. Supported by Voyage, Jina, and Pinecone. ' type: boolean default: false max_tokens_per_doc: description: 'Maximum number of tokens per document. Documents exceeding this limit will be truncated. Cohere-specific parameter. ' type: integer minimum: 1 priority: description: 'Request priority hint. Cohere-specific parameter. ' type: number rank_fields: description: 'The fields to use for ranking when documents are objects with multiple fields. Pinecone-specific parameter. ' type: array items: type: string example: - text - title truncation: description: 'Whether to truncate documents that exceed the model''s maximum context length. Voyage-specific parameter. ' type: boolean parameters: description: 'Additional provider-specific parameters. Pinecone-specific parameter. ' type: object additionalProperties: true required: - model - query - documents CreateRerankResponse: type: object description: Response from the rerank endpoint. properties: id: type: string description: A unique identifier for the rerank request. example: rerank-abc123 object: type: string description: The object type, which is always "list". enum: - list example: list results: type: array description: 'The reranked results sorted by relevance score in descending order. ' items: $ref: '#/components/schemas/RerankResult' model: type: string description: The model used for reranking. example: rerank-v3.5 usage: $ref: '#/components/schemas/RerankUsage' provider: type: string description: The provider that processed the request. example: cohere required: - object - results - model RerankDocument: description: 'A document to be reranked. Can be a simple string or an object with a text field and optional metadata. ' oneOf: - type: string title: string description: A simple text string to be reranked. example: Paris is the capital of France. - type: object title: object description: An object containing the document text and optional metadata. properties: text: type: string description: The text content of the document. example: Paris is the capital of France. required: - text additionalProperties: true securitySchemes: Portkey-Key: type: apiKey in: header name: x-portkey-api-key Virtual-Key: type: apiKey in: header name: x-portkey-virtual-key Provider-Auth: type: http scheme: bearer Provider-Name: type: apiKey in: header name: x-portkey-provider Config: type: apiKey in: header name: x-portkey-config Custom-Host: type: apiKey in: header name: x-portkey-custom-host x-server-groups: ControlPlaneServers: - url: https://api.portkey.ai/v1 description: Portkey API Public Endpoint - url: SELF_HOSTED_CONTROL_PLANE_URL description: Self-Hosted Control Plane URL DataPlaneServers: - url: https://api.portkey.ai/v1 description: Portkey API Public Endpoint - url: SELF_HOSTED_GATEWAY_URL description: Self-Hosted Gateway URL PublicServers: - url: https://api.portkey.ai description: Portkey Public API (no auth required) x-mint: mcp: enabled: true name: Portkey MCP description: Official MCP Server for Portkey Docs & APIs x-code-samples: navigationGroups: - id: endpoints title: Endpoints - id: assistants title: Assistants - id: legacy title: Legacy groups: - id: audio title: Audio description: 'Learn how to turn audio into text or text into audio. Related guide: [Speech to text](https://platform.openai.com/docs/guides/speech-to-text) ' navigationGroup: endpoints sections: - type: endpoint key: createSpeech path: createSpeech - type: endpoint key: createTranscription path: createTranscription - type: endpoint key: createTranslation path: createTranslation - type: object key: CreateTranscriptionResponseJson path: json-object - type: object key: CreateTranscriptionResponseVerboseJson path: verbose-json-object - id: chat title: Chat description: 'Given a list of messages comprising a conversation, the model will return a response. Related guide: [Chat Completions](https://platform.openai.com/docs/guides/text-generation) ' navigationGroup: endpoints sections: - type: endpoint key: createChatCompletion path: create - type: object key: CreateChatCompletionResponse path: object - type: object key: CreateChatCompletionStreamResponse path: streaming - id: realtime title: Realtime description: 'WebSocket proxy for provider Realtime APIs (`GET` upgrade). Use `wss://` with the same `/v1` data-plane base as other gateway routes. Related guide: [OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime) ' navigationGroup: endpoints sections: - type: endpoint key: connectRealtime path: connect - id: embeddings title: Embeddings description: 'Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms. Related guide: [Embeddings](https://platform.openai.com/docs/guides/embeddings) ' navigationGroup: endpoints sections: - type: endpoint key: createEmbedding path: create - type: object key: Embedding path: object - id: rerank title: Rerank description: 'Rerank a list of documents based on their relevance to a query. Reranking improves search results by scoring documents based on semantic relevance rather than keyword matching. Supported providers: Cohere, Voyage, Jina, Pinecone, Bedrock, Azure AI. ' navigationGroup: endpoints sections: - type: endpoint key: createRerank path: create - type: object key: CreateRerankResponse path: object - id: fine-tuning title: Fine-tuning description: 'Manage fine-tuning jobs to tailor a model to your specific training data. Related guide: [Fine-tune models](https://platform.openai.com/docs/guides/fine-tuning) ' navigationGroup: endpoints sections: - type: endpoint key: createFineTuningJob path: create - type: endpoint key: listPaginatedFineTuningJobs path: list - type: endpoint key: listFineTuningEvents path: list-events - type: endpoint key: listFineTuningJobCheckpoints path: list-checkpoints - type: endpoint key: retrieveFineTuningJob path: retrieve - type: endpoint key: cancelFineTuningJob path: cancel - type: object key: FinetuneChatRequestInput path: chat-input - type: object key: FinetuneCompletionRequestInput path: completions-input - type: object key: FineTuningJob path: object - type: object key: FineTuningJobEvent path: event-object - type: object key: FineTuningJobCheckpoint path: checkpoint-object - id: batch title: Batch description: 'Create large batches of API requests for asynchronous processing. The Batch API returns completions within 24 hours for a 50% discount. Related guide: [Batch](https://platform.openai.com/docs/guides/batch) ' navigationGroup: endpoints sections: - type: endpoint key: createBatch path: create - type: endpoint key: retrieveBatch path: retrieve - type: endpoint key: cancelBatch path: cancel - type: endpoint key: listBatches path: list - type: object key: Batch path: object - type: object key: BatchRequestInput path: request-input - type: object key: BatchRequestOutput path: request-output - id: files title: Files description: 'Files are used to upload documents that can be used with features like [Assistants](https://platform.openai.com/docs/api-reference/assistants), [Fine-tuning](https://platform.openai.com/docs/api-reference/fine-tuning), and [Batch API](https://platform.openai.com/docs/guides/batch). ' navigationGroup: endpoints sections: - type: endpoint key: createFile path: create - type: endpoint key: listFiles path: list - type: endpoint key: retrieveFile path: retrieve - type: endpoint key: deleteFile path: delete - type: endpoint key: downloadFile path: retrieve-contents - type: object key: OpenAIFile path: object - id: images title: Images description: 'Given a prompt and/or an input image, the model will generate a new image. Related guide: [Image generation](https://platform.openai.com/docs/guides/images) ' navigationGroup: endpoints sections: - type: endpoint key: createImage path: create - type: endpoint key: createImageEdit path: createEdit - type: endpoint key: createImageVariation path: createVariation - type: object key: Image path: object - id: models title: Models description: 'List and describe the various models available in the API. You can refer to the [Models](https://platform.openai.com/docs/models) documentation to understand what models are available and the differences between them. ' navigationGroup: endpoints sections: - type: endpoint key: listModels path: list - type: endpoint key: retrieveModel path: retrieve - type: endpoint key: deleteModel path: delete - type: object key: Model path: object - id: moderations title: Moderations description: 'Given some input text, outputs if the model classifies it as potentially harmful across several categories. Related guide: [Moderations](https://platform.openai.com/docs/guides/moderation) ' navigationGroup: endpoints sections: - type: endpoint key: createModeration path: create - type: object key: CreateModerationResponse path: object - id: assistants title: Assistants beta: true description: 'Build assistants that can call models and use tools to perform tasks. [Get started with the Assistants API](https://platform.openai.com/docs/assistants) ' navigationGroup: assistants sections: - type: endpoint key: createAssistant path: createAssistant - type: endpoint key: listAssistants path: listAssistants - type: endpoint key: getAssistant path: getAssistant - type: endpoint key: modifyAssistant path: modifyAssistant - type: endpoint key: deleteAssistant path: deleteAssistant - type: object key: AssistantObject path: object - id: threads title: Threads beta: true description: 'Create threads that assistants can interact with. Related guide: [Assistants](https://platform.openai.com/docs/assistants/overview) ' navigationGroup: assistants sections: - type: endpoint key: createThread path: createThread - type: endpoint key: getThread path: getThread - type: endpoint key: modifyThread path: modifyThread - type: endpoint key: deleteThread path: deleteThread - type: object key: ThreadObject path: object - id: messages title: Messages beta: true description: 'Create messages within threads Related guide: [Assistants](https://platform.openai.com/docs/assistants/overview) ' navigationGroup: assistants sections: - type: endpoint key: createMessage path: createMessage - type: endpoint key: listMessages path: listMessages - type: endpoint key: getMessage path: getMessage - type: endpoint key: modifyMessage path: modifyMessage - type: endpoint key: deleteMessage path: deleteMessage - type: object key: MessageObject path: object - id: runs title: Runs beta: true description: 'Represents an execution run on a thread. Related guide: [Assistants](https://platform.openai.com/docs/assistants/overview) ' navigationGroup: assistants sections: - type: endpoint key: createRun path: createRun - type: endpoint key: createThreadAndRun path: createThreadAndRun - type: endpoint key: listRuns path: listRuns - type: endpoint key: getRun path: getRun - type: endpoint key: modifyRun path: modifyRun - type: endpoint key: submitToolOuputsToRun path: submitToolOutputs - type: endpoint key: cancelRun path: cancelRun - type: object key: RunObject path: object - id: run-steps title: Run Steps beta: true description: 'Represents the steps (model and tool calls) taken during the run. Related guide: [Assistants](https://platform.openai.com/docs/assistants/overview) ' navigationGroup: assistants sections: - type: endpoint key: listRunSteps path: listRunSteps - type: endpoint key: getRunStep path: getRunStep - type: object key: RunStepObject path: step-object - id: vector-stores title: Vector Stores beta: true description: 'Vector stores are used to store files for use by the `file_search` tool. Related guide: [File Search](https://platform.openai.com/docs/assistants/tools/file-search) ' navigationGroup: assistants sections: - type: endpoint key: createVectorStore path: create - type: endpoint key: listVectorStores path: list - type: endpoint key: getVectorStore path: retrieve - type: endpoint key: modifyVectorStore path: modify - type: endpoint key: deleteVectorStore path: delete - type: object key: VectorStoreObject path: object - id: vector-stores-files title: Vector Store Files beta: true description: 'Vector store files represent files inside a vector store. Related guide: [File Search](https://platform.openai.com/docs/assistants/tools/file-search) ' navigationGroup: assistants sections: - type: endpoint key: createVectorStoreFile path: createFile - type: endpoint key: listVectorStoreFiles path: listFiles - type: endpoint key: getVectorStoreFile path: getFile - type: endpoint key: deleteVectorStoreFile path: deleteFile - type: object key: VectorStoreFileObject path: file-object - id: vector-stores-file-batches title: Vector Store File Batches beta: true description: 'Vector store file batches represent operations to add multiple files to a vector store. Related guide: [File Search](https://platform.openai.com/docs/assistants/tools/file-search) ' navigationGroup: assistants sections: - type: endpoint key: createVectorStoreFileBatch path: createBatch - type: endpoint key: getVectorStoreFileBatch path: getBatch - type: endpoint key: cancelVectorStoreFileBatch path: cancelBatch - type: endpoint key: listFilesInVectorStoreBatch path: listBatchFiles - type: object key: VectorStoreFileBatchObject path: batch-object - id: assistants-streaming title: Streaming beta: true description: 'Stream the result of executing a Run or resuming a Run after submitting tool outputs. You can stream events from the [Create Thread and Run](https://platform.openai.com/docs/api-reference/runs/createThreadAndRun), [Create Run](https://platform.openai.com/docs/api-reference/runs/createRun), and [Submit Tool Outputs](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoints by passing `"stream": true`. The response will be a [Server-Sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events) stream. Our Node and Python SDKs provide helpful utilities to make streaming easy. Reference the [Assistants API quickstart](https://platform.openai.com/docs/assistants/overview) to learn more. ' navigationGroup: assistants sections: - type: object key: MessageDeltaObject path: message-delta-object - type: object key: RunStepDeltaObject path: run-step-delta-object - type: object key: AssistantStreamEvent path: events - id: completions title: Completions legacy: true navigationGroup: legacy description: 'Given a prompt, the model will return one or more predicted completions along with the probabilities of alternative tokens at each position. Most developer should use our [Chat Completions API](https://platform.openai.com/docs/guides/text-generation/text-generation-models) to leverage our best and newest models. ' sections: - type: endpoint key: createCompletion path: create - type: object key: CreateCompletionResponse path: object