GurbaniNow Getting Started: API Keys and First Request (2026)

Getting started overview

To begin integrating the GurbaniNow API, developers typically follow a sequence of steps designed to ensure secure access and successful data retrieval. This process involves creating a GurbaniNow account, generating API keys, and then using these credentials to make an initial API call. The GurbaniNow API provides access to Sikh scriptures, including Gurmukhi text and translations, which can be incorporated into various applications and platforms. The API is designed for straightforward integration, with detailed documentation available to guide developers through the process.

The GurbaniNow platform offers a free tier for personal use, allowing developers to test and build non-commercial projects without an initial financial commitment. For commercial applications or higher request volumes, paid tiers are available, starting at $10 per month for up to 200,000 requests. The API supports standard RESTful principles, making it accessible for developers familiar with common web API interaction patterns. Primary language examples are provided in JavaScript, catering to a wide range of web and application development environments.

This guide focuses on the critical initial steps: account creation, API key acquisition, and executing a first working request. By completing these steps, developers will establish a foundational understanding and functional setup for further development with GurbaniNow.

Create an account and get keys

Accessing the GurbaniNow API requires an active account and valid API keys. These keys authenticate your requests and link them to your usage plan, whether it's the free personal tier or a paid subscription. The process for obtaining these credentials is designed to be straightforward:

1. Navigate to the GurbaniNow Website: Begin by visiting the GurbaniNow homepage.
2. Sign Up for an Account: Look for a 'Sign Up' or 'Register' option. You will typically be prompted to provide an email address and create a password. Follow any on-screen instructions to complete the registration process, which may include email verification.
3. Access the Developer Dashboard: Once your account is created and verified, log in to access your personal dashboard. This dashboard is the central hub for managing your API usage, viewing analytics, and generating API keys.
4. Generate API Keys: Within the dashboard, locate a section related to 'API Keys', 'Developer Settings', or 'Credentials'. There, you should find an option to generate a new API key. GurbaniNow typically issues a single API key that acts as a unique identifier for your application. Copy this key immediately and store it securely. Treat your API key like a password; it grants access to your account's API quota and should not be exposed in public code repositories or client-side applications without proper proxying.

The API key is a critical component for all subsequent API calls. Without it, the GurbaniNow API will reject your requests as unauthorized. For enhanced security, consider environment variables or secure configuration files to store your API key in production environments, as recommended by general API key security best practices.

Your first request

Once you have obtained your GurbaniNow API key, you can proceed to make your first request. This example demonstrates how to fetch a specific Shabad (hymn) using a simple HTTP GET request. The GurbaniNow API typically returns data in JSON format, which is a widely adopted standard for web APIs.

Before making a request, ensure you have a tool capable of sending HTTP requests. curl is a common command-line tool, and JavaScript's fetch API is widely used in web development.

Using curl (Command Line)

Open your terminal or command prompt and execute the following command. Replace YOUR_API_KEY with the actual API key you generated from your GurbaniNow dashboard.

curl -X GET \
  "https://api.gurbaninow.com/v2/shabad?id=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

This curl command requests Shabad with id=1 from the GurbaniNow API. The -H "Authorization: Bearer YOUR_API_KEY" header is crucial for authenticating your request. A successful response will return a JSON object containing the Shabad's details, including Gurmukhi text, transliteration, and translations.

Using JavaScript (Web Browser/Node.js)

For JavaScript environments, you can use the fetch API. This example can be run in a browser's developer console or within a Node.js environment (with a polyfill or by using a library like node-fetch).

const apiKey = 'YOUR_API_KEY'; // Replace with your actual GurbaniNow API key

async function fetchShabad() {
  try {
    const response = await fetch('https://api.gurbaninow.com/v2/shabad?id=1', {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Shabad Data:', data);
  } catch (error) {
    console.error('Error fetching Shabad:', error);
  }
}

fetchShabad();

This JavaScript code snippet performs the same request as the curl example. It sets the Authorization header with your API key and then parses the JSON response. The console.log statement will output the retrieved Shabad data to your console.

Upon a successful request, you should receive a JSON response similar to the following (simplified for brevity):

{
  "shabad": {
    "id": 1,
    "gurmukhi": "ੴ ਸਤਿ ਨਾਮੁ ਕਰਤਾ ਪੁਰਖੁ ਨਿਰਭਉ ਨਿਰਵੈਰੁ ਅਕਾਲ ਮੂਰਤਿ ਅਜੂਨੀ ਸੈਭੰ ਗੁਰ ਪ੍ਰਸਾਦਿ॥",
    "transliteration": "ik-oam-kaar sat naam kartaa purakh nirbha-o nirvair akaal moorat ajoonee saibhang gur parsaad.",
    "translation": {
      "english": "One Universal Creator God. The Name Is Truth. Creative Being Personified. No Fear. No Hatred. Image Of The Undying, Beyond Birth, Self-Existent. By Guru's Grace." 
    }
    // ... more data
  }
}

This response confirms that your API key is valid and your application can successfully communicate with the GurbaniNow API. For a comprehensive list of available endpoints and their parameters, refer to the official GurbaniNow API documentation.

Common next steps

After successfully making your first request to the GurbaniNow API, several common next steps can help you further integrate and utilize its capabilities:

1. Explore More Endpoints: The GurbaniNow API offers various endpoints beyond fetching a single Shabad by ID. You might want to explore endpoints for searching Gurbani text, retrieving Ang (page) data, or accessing specific authors and Raags. Consult the GurbaniNow API reference for a complete list and detailed descriptions of each endpoint's functionality and parameters. Understanding the full range of available data will enable you to build more comprehensive applications.
2. Implement Error Handling: Robust applications require proper error handling. The GurbaniNow API will return specific HTTP status codes and error messages for issues such as invalid API keys, rate limits, or malformed requests. Implement logic in your application to gracefully handle these errors, providing informative feedback to users or logging issues for debugging. For example, a 401 Unauthorized status typically indicates an issue with the API key.
3. Manage API Key Security: Reiterate the importance of keeping your API key secure. For client-side applications, consider using a backend proxy to make API calls, preventing your key from being exposed in public client-side code. For server-side applications, use environment variables or a secure secrets management system. This practice aligns with general security recommendations for API keys, as outlined by resources such as the Twilio API Key Guide.
4. Understand Rate Limits: Review the GurbaniNow API's rate limit policies, detailed in their documentation. Exceeding these limits can result in temporary blocks or throttled requests. Design your application to respect these limits, potentially by caching data, implementing exponential backoff for retries, or optimizing your data fetching strategy.
5. Utilize SDKs (if applicable): If you are developing in JavaScript, GurbaniNow provides an official JavaScript SDK. Using an SDK can simplify API interactions by abstracting away the raw HTTP requests and handling authentication, error parsing, and data serialization. This can lead to cleaner, more maintainable code and faster development.
6. Plan for Scalability and Caching: For applications expecting significant traffic, consider how you will scale your usage of the GurbaniNow API. Implementing a caching strategy for frequently requested data can reduce the number of API calls, improve application performance, and help stay within rate limits.
7. Explore Community and Support: If you encounter complex issues or have specific questions, check if GurbaniNow offers community forums, support channels, or a developer community where you can seek assistance or share insights.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some typical problems and their solutions when working with the GurbaniNow API:

• 401 Unauthorized Error:
  • Problem: This is the most frequent error, indicating that your API key is either missing, incorrect, or expired.
  • Solution: Double-check that you have included the Authorization: Bearer YOUR_API_KEY header in your request. Ensure there are no typos in your API key. Generate a new key from your GurbaniNow dashboard if you suspect the current one is compromised or invalid. Verify that your account is active and not suspended.
• 403 Forbidden Error:
  • Problem: This error often suggests that your account or API key does not have the necessary permissions to access the requested resource, or you might be trying to access a paid feature on a free tier.
  • Solution: Review your GurbaniNow account's subscription level and the specific endpoint you are trying to access. Some endpoints or higher request volumes might require a paid plan.
• 404 Not Found Error:
  • Problem: The requested resource (e.g., a specific Shabad ID) does not exist or the URL is incorrect.
  • Solution: Verify the API endpoint URL against the GurbaniNow API documentation. Ensure any parameters, like id in /v2/shabad?id=1, correspond to existing resources.
• 429 Too Many Requests Error:
  • Problem: You have exceeded the API's rate limits.
  • Solution: Pause your requests and wait for the rate limit window to reset. Implement exponential backoff in your application to automatically retry requests after a delay. Review GurbaniNow's rate limit policies to understand the thresholds and design your application to stay within them.
• CORS Policy Error (Browser Only):
  • Problem: If you are making requests directly from a web browser (client-side JavaScript) to a different domain, you might encounter Cross-Origin Resource Sharing (CORS) errors.
  • Solution: GurbaniNow's API typically supports CORS. If you still encounter issues, ensure your browser is not blocking requests due to extensions. For production applications, consider using a backend proxy server to make API calls, which bypasses client-side CORS restrictions.
• Network Issues:
  • Problem: General connectivity problems preventing your request from reaching the GurbaniNow servers.
  • Solution: Check your internet connection. Try accessing other websites to confirm network connectivity. If you are behind a corporate firewall, ensure that API endpoints are whitelisted.

When troubleshooting, always consult the GurbaniNow API documentation for specific error codes and their meanings. Using tools like your browser's developer console (for network requests) or a command-line HTTP client with verbose output (e.g., curl -v) can provide more detailed insights into the request and response headers, which are invaluable for diagnosing problems.