Skip to main content

Quickstart Guide

This guide will walk you through making your first API call to Unizo in under 5 minutes.

Prerequisites

Step 1: Install the SDK (Optional)

While you can use any HTTP client, our SDKs make integration easier:

npm install @unizo/sdk

Step 2: List Available Connectors

First, let's see what integrations are available:

import { UnizoClient } from '@unizo/sdk';

const client = new UnizoClient({
apiKey: process.env.UNIZO_API_KEY
});

async function listConnectors() {
try {
const connectors = await client.connectors.list();
console.log('Available connectors:', connectors);
} catch (error) {
console.error('Error:', error.message);
}
}

listConnectors();

Expected response:

{
"connectors": [
{
"id": "github",
"name": "GitHub",
"category": "source-code",
"status": "available"
},
{
"id": "jira",
"name": "Jira",
"category": "ticketing",
"status": "available"
},
{
"id": "slack",
"name": "Slack",
"category": "communications",
"status": "available"
}
]
}

Step 3: Connect a Service

Let's connect GitHub as an example:

async function connectGitHub() {
try {
const connection = await client.connectors.connect('github', {
token: 'your_github_token_here',
organization: 'your-org' // optional
});

console.log('Connected to GitHub:', connection);
return connection.id;
} catch (error) {
console.error('Connection failed:', error.message);
}
}

const connectionId = await connectGitHub();

Step 4: Make Your First Unified API Call

Now let's use the unified ticketing API to list issues from GitHub:

async function listIssues() {
try {
const issues = await client.ticketing.list({
connection_id: connectionId,
status: 'open'
});

console.log('Open issues:', issues);
return issues;
} catch (error) {
console.error('Failed to fetch issues:', error.message);
}
}

const issues = await listIssues();

Expected response:

{
"issues": [
{
"id": "issue_123",
"title": "Fix authentication bug",
"status": "open",
"priority": "high",
"assignee": {
"id": "user_456",
"name": "John Doe",
"email": "john@example.com"
},
"created_at": "2024-01-01T10:00:00Z",
"updated_at": "2024-01-01T15:30:00Z",
"labels": ["bug", "authentication"]
}
],
"pagination": {
"page": 1,
"per_page": 50,
"total": 1
}
}

Step 5: Create a New Issue

Let's create a new issue using the unified API:

async function createIssue() {
try {
const newIssue = await client.ticketing.create({
connection_id: connectionId,
title: 'Update documentation',
description: 'The API documentation needs to be updated with the latest changes.',
priority: 'medium',
labels: ['documentation', 'enhancement']
});

console.log('Created issue:', newIssue);
return newIssue;
} catch (error) {
console.error('Failed to create issue:', error.message);
}
}

const newIssue = await createIssue();

🎉 Congratulations!

You've successfully:

  • ✅ Listed available connectors
  • ✅ Connected a service (GitHub)
  • ✅ Listed issues using the unified API
  • ✅ Created a new issue

What's Next?

Now that you've made your first API calls, here are some next steps:

  1. Explore More APIs - Try our other unified APIs
  2. Set Up Webhooks - Get real-time notifications
  3. Try MCP Integration - Build AI agents with MCP
  4. Browse Integrations - Connect more services

Troubleshooting

Common Issues

Authentication Error (401)

  • Verify your API key is correct
  • Check that you're including the Authorization header
  • Ensure your API key has the required scopes

Connection Failed

  • Verify your service credentials (GitHub token, etc.)
  • Check that the service is accessible from your network
  • Review the connector documentation for specific requirements

Rate Limiting (429)

  • See our rate limiting guide
  • Implement exponential backoff in your requests
  • Consider upgrading your plan for higher limits

Need more help? Join our Discord community or contact support.