Using API Keys

What are API Keys?

API keys let you access Boise State AI Chat through code instead of the web interface. This is useful for automating tasks, building custom applications, or integrating AI into your existing workflows.

Key Points

One active key per user
Keys expire after 90 days
Usage counts against your monthly quota
API conversations are not saved to your chat history
Requires basic programming knowledge

Pro tip: Use AI to help you troubleshoot your code! This can be useful if you come across “invalid key” or 401 errors during the process. You can paste your code into the prompt window without the API key to get feedback on your code.

Getting Your API Key

Log into https://boisestate.ai/api-keys using your Boise State credentials.
Click or tap Create API Key and give it a name.
Save the key immediately - you can't retrieve it later!

Quick Start Examples

Simple Message Request

Send a single message and get a complete response.

Using curl

bash

curl -X POST https://api.boisestate.ai/chat/api-converse \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, how can you help me today?",
    "modelId": "us.amazon.nova-pro-v1:0",
    "temperature": 0.7,
    "maxTokens": 1000
  }'

Using Python

python

import requests

url = 'https://api.boisestate.ai/chat/api-converse'
headers = {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

payload = {
    'message': 'Hello, how can you help me today?',
    'modelId': 'us.amazon.nova-pro-v1:0',
    'temperature': 0.7,
    'maxTokens': 1000
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

print(data['text'])
print(f"Tokens: {data['usage']['inputTokens']}/{data['usage']['outputTokens']}")

Using JavaScript

javascript

const response = await fetch('https://api.boisestate.ai/chat/api-converse', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Hello, how can you help me today?',
    modelId: 'us.amazon.nova-pro-v1:0',
    temperature: 0.7,
    maxTokens: 1000
  })
});

const data = await response.json();
console.log(data.text);
console.log(`Tokens: ${data.usage.inputTokens}/${data.usage.outputTokens}`);

Conversation with Context

To maintain context across multiple exchanges, use the messages array format.

Using curl

bash

curl -X POST https://api.boisestate.ai/chat/api-converse \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      },
      {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      {
        "role": "user",
        "content": "What about Germany?"
      }
    ],
    "modelId": "us.amazon.nova-pro-v1:0",
    "systemPrompt": "You are a helpful geography assistant.",
    "temperature": 0.7
  }'

Using Python

python

import requests

url = 'https://api.boisestate.ai/chat/api-converse'
headers = {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

payload = {
    'messages': [
        {
            'role': 'user',
            'content': 'What is the capital of France?'
        },
        {
            'role': 'assistant',
            'content': 'The capital of France is Paris.'
        },
        {
            'role': 'user',
            'content': 'What about Germany?'
        }
    ],
    'modelId': 'us.amazon.nova-pro-v1:0',
    'systemPrompt': 'You are a helpful geography assistant.',
    'temperature': 0.7
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

print(data['text'])
print(f"Tokens: {data['usage']['inputTokens']}/{data['usage']['outputTokens']}")

Using JavaScript

javascript

const response = await fetch('https://api.boisestate.ai/chat/api-converse', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [
      {
        role: 'user',
        content: 'What is the capital of France?'
      },
      {
        role: 'assistant',
        content: 'The capital of France is Paris.'
      },
      {
        role: 'user',
        content: 'What about Germany?'
      }
    ],
    modelId: 'us.amazon.nova-pro-v1:0',
    systemPrompt: 'You are a helpful geography assistant.',
    temperature: 0.7
  })
});

const data = await response.json();
console.log(data.text);
console.log(`Tokens: ${data.usage.inputTokens}/${data.usage.outputTokens}`);

Streaming Responses (Real-time)

For word-by-word streaming output, use the /chat/api-chat endpoint.

Using Python

python

import requests
import json
from sseclient import SSEClient  # pip install sseclient-py

url = 'https://api.boisestate.ai/chat/api-chat'
headers = {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

payload = {
    'message': 'Tell me a short story about a robot.',
    'modelId': 'us.amazon.nova-pro-v1:0',
    'temperature': 0.7,
    'maxTokens': 1000
}

response = requests.post(url, headers=headers, json=payload, stream=True)
client = SSEClient(response)

for event in client.events():
    if event.event == 'delta' and event.data:
        data = json.loads(event.data)
        print(data.get('content', ''), end='', flush=True)
    elif event.event == 'stream_complete':
        break

Using JavaScript

javascript

const response = await fetch('https://api.boisestate.ai/chat/api-chat', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Tell me a short story about a robot.',
    modelId: 'us.amazon.nova-pro-v1:0',
    temperature: 0.7,
    maxTokens: 1000
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      if (data.type === 'content_delta') {
        process.stdout.write(data.delta);
      }
    }
  }
}

Request Parameters

Required:

message (string) OR messages (array) - Your input
modelId (string) - Which AI model to use

Optional:

systemPrompt (string) - Instructions for AI behavior
temperature (number, 0.0-1.0) - Response creativity (default: 0.7)
maxTokens (number) - Maximum response length
topP (number, 0.0-1.0) - Sampling parameter (default: 0.9)

Two Endpoints

EndpointUse CaseResponse/chat/api-converseSimple requests, batch processingComplete response at once (JSON)/chat/api-chatInteractive apps, real-time feedbackStreaming word-by-word (SSE)

Important Notes

No default system prompts: Unlike the web interface, API requests have no default instructions. Add a systemPrompt if you want to guide the AI's behavior.

No conversation memory: Each request is independent. To maintain context, include previous messages in the messages array.

Security

Never commit API keys to code repositories
Store keys in environment variables
Treat them like passwords

Common Errors

401 Unauthorized: Invalid or expired API key
403 Forbidden: Monthly quota exceeded
400 Bad Request: Check your request format (can't send both message and messages)

Need Help?

Manage your keys: https://boisestate.ai/api-keys.
Full documentation: Available on the api-keys page.