Clarity API and Portkey

The Clarity Platform and Portkey enable Yale faculty, staff, and sponsored students to secure and scalable API offerings allowing AI capabilities to be built into applications and workflows. These services are designed to meet different integration needs and are available at different price levels. Please refer to API pricing page for more information.

What is an API?

An API (Application Programming Interface) acts as a messenger that enables different software applications to communicate with each other. When interacting with a Large Language Model (LLM), an API allows you to programmatically send prompts to the model and receive responses.

Jump to a Section

Clarity API

Integrate custom AI agents with specialized knowledge, system instructions, and advanced capabilities directly into your applications via API access.

Learn More About Clarity API

Portkey

Access to raw AI models from AWS, Azure, and GCP through a unified API interface for building custom AI workflows and applications.

Learn More About Portkey

Clarity API: Custom Agent Integration

Clarity API provides programmatic access to a Clarity custom AI agent. Rather than requiring users to engage with Custom Agents through the Clarity user portal, your applications may interface with these agents via API calls—facilitated by the use of Agent Access Tokens—enabling seamless integration of custom AI agents directly into your applications or workflows.

Core Capabilities

  • Access to leading AI models: For a complete overview of the Agents and underlying AI models available, please refer to the Agents page.
  • Built-in capabilities: Advanced features like file uploads, file search, and a code interpreter are included, providing similar robust functionality found in commercial platforms such as ChatGPT and Claude.ai.
  • Custom Agents: Build and call Custom Agents that use your knowledge sources to ground agent responses.
  • Knowledge grounding: Retrieval-Augmented Generation (RAG) built-in to ground the agent’s responses in your data.

Configuring and Calling Custom Agents

For tailored use cases where you want to interact programmatically with your Custom Agent through API, Clarity supports self-service creation and management of Custom Agents. Through the Clarity user portal, you can:

  1. Customize System Instructions: Define exactly how the agent should behave, its persona, and its constraints.
  2. Attach Knowledge Sources: Ground the agent’s responses in specific, relevant data via Retrieval-Augmented Generation (RAG).
  3. Generate an Agent Access Token: Once your Custom Agent is configured, you need to reach out to the AI Platform Services team to have them generate and distribute an API token for you. Instead of interacting with the agent through the Clarity user portal, your applications can call this token via API to integrate the agent’s highly specialized functionality and knowledge into your own application.
Clarity API Technical Documentation

Portkey: Unified AI API Gateway

Portkey is an API gateway SaaS offering that provides streamlined, proxy access to AI models hosted across major cloud providers including AWS, GCP, and Azure. It eliminates the complexity of setting up complex cloud provider infrastructure, configurations, and billing.

Core Capabilities

  • Simplified API Key Management: Easily create, distribute, and rotate API keys.
  • Multi-Cloud Proxy: Route requests to AWS, GCP, or Azure seamlessly through a single, unified API interface.
  • Usage Dashboard: Real-time cost and token tracking.
  • Cost and Budget Controls: Set budget limits on API keys to prevent cost overruns.
  • Traffic Management: Set and enforce rate limits, such as Requests Per Minute (RPM) and Tokens Per Minute (TPM).
Portkey Technical Documentation

Which Service Should You Choose?

Use this quick reference guide to determine which API option is right for your use case.

Need Clarity API Portkey API Gateway
Best For… Integrating a pre-configured, context-aware custom AI agent into an application. Connect directly to AI models and customize how they work within your applications.
Use Case RAG, customized system prompts, specialized tasks, and document querying. Building applications from scratch using LangChain, LlamaIndex, or raw API calls.
Setup Complexity Low: Configure the agent in the Clarity self-service portal and get an Agent Access Token to call the agent. Medium: Requires handling your own prompts, context, and integrations.
Cost Control N/A Real-time cost tracking with the option to implement appropriate rate and budget limits.
Usage Tracking Access to periodically updated Power BI report to track and monitor usage. Dashboard to track and monitor usage in real time.
Infrastructure Managed by AI Platform Services & FoundationaLLM. Proxies to Azure, AWS, and GCP.

Students

Access to manage custom agents or API keys must be sponsored by a professor and their contact information included on the request form.

Request API Access

Ready to request access? Familiarize yourself with the process of getting access to API.

Learn More

API Use Case Examples

Both Clarity API and Portkey can be adapted to a wide range of use cases. The following examples demonstrate how API keys are being used in different solutions across Yale.

Ensuring compliance on sponsored research projects is critical and highly complex, with federal and agency regulations running to several hundred pages. To support staff with navigating this complexity, Yale Finance is developing a self-service custom agent in Clarity which units can utilize to pre-review their submission of cost transfers, which entails the movement of expenses to or from sponsored projects. Goals of the Agent include further enhancing cost transfer submission quality, reducing re-work, saving time, and supporting staff training.

Version 1.0 of the Agent piloted with various units relied on the underlying LLM’s extensive training on federal and agency regulations supplemented by bespoke system instructions guiding the agent on several Yale-specific rules pertaining to cost transfers.  Version 2.0 of the Agent will leverage powerful new functionality in Clarity, such as equipping the Agent with knowledge sources including all relevant Yale policies, procedures, and forms.  Applying an agile, continuous improvement approach, enhancements to the Agent are identified and validated through a combination of user feedback and systematic, large-scale testing performed utilizing API access to the Agent.

The Educational Technology and Innovation (ETI) team at the School of Medicine used API access to develop a tool for summary of verbal feedback to students. The use case had the AI-powered tool automate the transcription and analysis of conversations between medical students, standardized patients, and instructors during simulation workshops, delivering both structured written educational feedback and clinical notes in real time. The tool integrates OpenAI’s Whisper for speech‑to‑text transcription and Gemini 2.5 Flash via Clarity AI within a web application hosted on Yale’s SpinUp server. 
 
The use case highlights the potential of an AI-driven tool to simultaneously enhance educational feedback and clinical notes for trainees during simulated encounters. Achieving faster performance remains key to meeting user expectations, and a more extensive validation phase involving a larger group of faculty is planned for March 2026. 

The Data Intensive Social Science Center (DISSC) used API access to standardize data sets of unstructured and unformatted public data. Street addresses were standardized prior to using them in a geocoder tool. The goal was to increase the data quality and provide more accurate results and better support research and teaching projects relying on geocoded data.  

Responsibilities of API Key Owners

Users with API access to Clarity or Portkey are expected to take responsibility for:

For All API Users

  • Key security: API keys are rotated every 90 days to prevent unauthorized access; users can choose to rotate them sooner if needed.
  • Compliance: Following data guidelines and using the API key for the approved use case only.
    • Note that a new use case requires an additional request.
  • Cost monitoring: Track token and cost usage.
  • User communication: Clearly disclose to end-users when AI is being used.
  • Maintain application: Test outputs for accuracy, bias, and appropriateness for your application. 
  • Annual attestation: Confirm adherence to safety and usage guidelines yearly.
  • Contact updates: Notify AI Platforms Services if primary contact changes or you leave Yale.
  • End-user support: Assist users experiencing issues with your agent integration.

Clarity API Specific Responsibilities

  • Agent maintenance: Keep Custom Agents’ knowledge sources current.
  • Agent access management: Review and update who can access your Custom Agent.
  • Lifecycle management: End-dating agents no longer in use.

Portkey Specific Responsibilities

  • Budget management: Set and monitor spending limits per key.

Support

The AI Platforms Services Team offers the following support:

  • Email us anytime at ai.platforms@yale.edu.
  • Join weekly office hours (details will be provided in the onboarding email).
  • Join the AI Platforms Community of Practice (invite will be provided in the onboarding email).

To learn more about the expected level of support, please review our Self-Service and Support Guidelines.