Skip to main content

​
Quickstart Guide

This guide will help you make your first API call to Nexus in just 5 minutes. By the end, you’ll have created a chat session and sent your first message.

​
Prerequisites

Before you begin, make sure you have:

Nexus Account

Sign up at nexusgpt.io if you haven’t already

API Key

Generate an API key from your dashboard (see Authentication)

​
Step 1: Set Up Your Environment

First, store your API key securely as an environment variable: 
export NEXUS_API_KEY="your_api_key_here"

​
Step 2: Create a Chat Session

Let’s create your first chat session. This establishes a conversation thread with your AI agent. 
curl -X POST https://api.nexusgpt.io/api/public/thread \
  -H "Content-Type: application/json" \
  -H "api-key: $NEXUS_API_KEY" \
  -d '{"message": "Hello! I need help with my order."}'
Expected Response: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2024-01-20T10:30:00Z"
}
Save the id from the response - you’ll need it to send messages to this session.

​
Step 3: Send a Message

Now let’s send a follow-up message to the session we just created: 
# Replace SESSION_ID with the id from Step 2
curl -X POST https://api.nexusgpt.io/api/public/thread/SESSION_ID/messages \
  -H "Content-Type: application/json" \
  -H "api-key: $NEXUS_API_KEY" \
  -d '{"message": "My order number is #12345"}'

​
Step 4: Retrieve Messages

To see the conversation history, including the AI’s responses: 
curl -X GET "https://api.nexusgpt.io/api/public/thread/SESSION_ID/messages?limit=10" \
  -H "api-key: $NEXUS_API_KEY"
Expected Response: 
[
  {
    "id": "msg_001",
    "type": "user",
    "content": "Hello! I need help with my order.",
    "createdAt": "2024-01-20T10:30:00Z"
  },
  {
    "id": "msg_002",
    "type": "assistant",
    "content": "I'd be happy to help you with your order! Could you please provide your order number?",
    "createdAt": "2024-01-20T10:30:05Z"
  },
  {
    "id": "msg_003",
    "type": "user",
    "content": "My order number is #12345",
    "createdAt": "2024-01-20T10:31:00Z"
  },
  {
    "id": "msg_004",
    "type": "assistant",
    "content": "Thank you! I'm looking up order #12345 for you now...",
    "createdAt": "2024-01-20T10:31:05Z"
  }
]

​
Complete Working Example

Here’s a complete example that ties everything together: 
const axios = require('axios');

class NexusQuickstart {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.nexusgpt.io/api/public';
  }

  async run() {
    try {
      // Step 1: Create a session
      console.log('Creating session...');
      const session = await this.createSession('Hello! I need help.');
      console.log('Session ID:', session.id);

      // Step 2: Send a message
      console.log('\nSending message...');
      await this.sendMessage(session.id, 'Can you help me track my order?');

      // Step 3: Wait for response
      console.log('\nWaiting for response...');
      await new Promise(resolve => setTimeout(resolve, 2000));

      // Step 4: Get messages
      console.log('\nRetrieving conversation...');
      const messages = await this.getMessages(session.id);
      
      console.log('\n--- Conversation ---');
      messages.forEach(msg => {
        console.log(`${msg.type.toUpperCase()}: ${msg.content}`);
      });

    } catch (error) {
      console.error('Error:', error.message);
    }
  }

  async createSession(initialMessage) {
    const response = await axios.post(
      `${this.baseUrl}/thread`,
      { message: initialMessage },
      { headers: this.getHeaders() }
    );
    return response.data;
  }

  async sendMessage(sessionId, message) {
    const response = await axios.post(
      `${this.baseUrl}/thread/${sessionId}/messages`,
      { message },
      { headers: this.getHeaders() }
    );
    return response.data;
  }

  async getMessages(sessionId) {
    const response = await axios.get(
      `${this.baseUrl}/thread/${sessionId}/messages`,
      { 
        headers: { 'api-key': this.apiKey },
        params: { limit: 20, order: 'asc' }
      }
    );
    return response.data;
  }

  getHeaders() {
    return {
      'Content-Type': 'application/json',
      'api-key': this.apiKey
    };
  }
}

// Run the quickstart
const quickstart = new NexusQuickstart(process.env.NEXUS_API_KEY);
quickstart.run();

​
Next Steps

Congratulations! You’ve successfully:
  • ✅ Created a chat session
  • ✅ Sent messages to your AI agent
  • ✅ Retrieved conversation history
Now explore more advanced features:

API Reference

Explore all available endpoints and parameters

SDK Examples

Find complete examples in multiple languages

Error Handling

Learn how to handle errors gracefully

Best Practices

Optimize your integration for production

​
Troubleshooting

  • Verify your API key is correct
  • Check that the header name is exactly api-key
  • Ensure there are no extra spaces or characters
  • Confirm you’re using the correct session ID
  • Check that the session hasn’t expired
  • Try creating a new session
  • Wait a bit longer (2-3 seconds) before fetching messages
  • Check that your agent is properly configured
  • Verify the agent has the necessary permissions
Need help? Contact support at [email protected]