Semantria Getting Started: Account, Keys, & First Request (2026)

Getting started overview

Integrating with Semantria for natural language processing (NLP) involves a series of steps designed to get you from account creation to making your first authenticated API call. Semantria provides a RESTful API for text analytics, including sentiment analysis, entity extraction, and text categorization. The service is primarily accessed via HTTP requests, with official SDKs available to streamline development in several programming languages.

This guide outlines the essential steps to configure your environment and execute a basic text analysis operation. It covers creating an account, locating your API keys, and constructing a foundational request. Understanding these initial steps is crucial for leveraging Semantria's capabilities for tasks such as customer feedback analysis or social media monitoring.

The following table summarizes the key stages for a rapid onboarding:

Create an account and get keys

To begin using Semantria, you must first create an account. Semantria offers a Developer Plan that includes 5,000 API calls per month, suitable for initial testing and development. Navigate to the Semantria pricing page and select the Developer Plan to initiate the signup process.

Upon successful registration and account activation, you will gain access to the Semantria dashboard. Within this dashboard, your API Key and API Secret are prominently displayed. These credentials are vital for authenticating all requests made to the Semantria API. The API Key identifies your application, while the API Secret is used to sign your requests, ensuring their integrity and authenticity. It is crucial to keep your API Secret confidential to prevent unauthorized access to your account and API quota.

For security best practices, review general OAuth 2.0 client credential flows, which Semantria's authentication model broadly follows, to understand secure handling of API keys and secrets OAuth 2.0 specification overview. Treat these credentials as sensitive information, similar to passwords.

Your first request

After obtaining your API Key and Secret, you can proceed to make your first request. Semantria provides SDKs for several popular programming languages, including Python, Java, and Node.js. Using an SDK is often the most straightforward approach for new integrations, as it abstracts the complexities of HTTP request construction and authentication.

Using the Python SDK

If you choose to use the Python SDK, ensure you have Python installed. You can install the Semantria Python SDK using pip:

pip install semantria

Here's a basic Python example to analyze a text string:

from semantria.session import Session

# Replace with your actual API Key and Secret
CONSUMER_KEY = 'YOUR_API_KEY'
CONSUMER_SECRET = 'YOUR_API_SECRET'

session = Session(CONSUMER_KEY, CONSUMER_SECRET, verify_ssl_cert=True)

documents = [
    {"id": "testdoc1", "text": "Semantria offers advanced text analytics capabilities."},
    {"id": "testdoc2", "text": "The API is designed for straightforward integration."}
]

# Queue documents for processing
initial_queue_status = session.queue_batch(documents)
print(f"Initial queue status: {initial_queue_status}")

# Retrieve processed results (may require a short delay)
import time
time.sleep(5) # Wait for processing

processed_results = session.get_processed_documents()

for doc in processed_results:
    print(f"Document ID: {doc['id']}")
    if 'sentiment_score' in doc:
        print(f"  Sentiment Score: {doc['sentiment_score']}")
    if 'entities' in doc:
        print("  Entities:")
        for entity in doc['entities']:
            print(f"    - {entity['title']} ({entity['entity_type']})")
    print("\n")

This script initializes a session, queues two sample documents for analysis, waits a short period for processing, and then retrieves the results, printing out sentiment scores and extracted entities. More detailed examples and SDKs for other languages are available in the Semantria Help Portal.

Raw HTTP Request Example with cURL

If you prefer to interact directly with the API without an SDK, you can use tools like cURL. Semantria's API uses OAuth 1.0a for authentication, requiring requests to be signed. While SDKs handle this automatically, a raw HTTP request involves constructing the OAuth signature manually or using a library that supports OAuth 1.0a.

Here's a conceptual representation of queueing a document using cURL. Note that generating the oauth_signature is complex for cURL and typically requires client-side code:

# This is a conceptual example. Generating the OAuth 1.0a signature requires a library.
# You would typically use an SDK or a programming language's OAuth library to do this.

# Example of a POST request to queue documents (signature generation omitted for brevity)
curl -X POST \
  "https://api.semantria.com/v2.0/app/documents.json" \
  -H "Content-Type: application/json" \
  -H "Authorization: OAuth oauth_consumer_key=\"YOUR_API_KEY\", oauth_token=\"\", oauth_signature_method=\"HMAC-SHA1\", oauth_timestamp=\"1678886400\", oauth_nonce=\"RANDOM_NONCE\", oauth_version=\"1.0\", oauth_signature=\"GENERATED_SIGNATURE\"" \
  -d '[{"id":"doc1","text":"Semantria is a text analytics service."}]'

For practical raw HTTP interactions, it's recommended to use a programming language's OAuth 1.0a library (e.g., requests-oauthlib in Python, oauth-1.0a in Node.js) to correctly generate the authorization header. The Semantria API 2.0 reference provides comprehensive details on request formats and authentication.

Common next steps

Once you've successfully made your first API call, you can explore Semantria's broader capabilities and integrate them further into your applications:

1. Explore Advanced Features: Review the Semantria API documentation to understand features like custom categories, sentiment phrases, and entity configurations. These allow you to tailor the analysis to specific domain needs.
2. Handle Asynchronous Processing: Semantria's API is asynchronous. You queue documents for processing and then retrieve the results later. Develop robust mechanisms to handle this asynchronous workflow, including polling for results and managing document IDs.
3. Error Handling and Retries: Implement proper error handling for API responses. Understand common error codes and implement retry mechanisms for transient network issues or rate limiting.
4. Batch Processing: For efficiency, process multiple documents in a single batch request rather than individual calls. This reduces API overhead and improves throughput.
5. Monitor Usage: Keep track of your API call usage through the Semantria dashboard to stay within your plan limits and plan for scaling.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here are some steps to troubleshoot problems:

• Check API Key and Secret: Double-check that your CONSUMER_KEY and CONSUMER_SECRET are copied correctly from your Semantria dashboard. Even minor typos will lead to authentication failures.
• Verify OAuth Signature: If you are making raw HTTP requests, ensure your OAuth 1.0a signature generation is correct. This is the most frequent source of error for non-SDK users. Consider using an SDK or an established OAuth 1.0a library.
• Review API Endpoint: Confirm you are using the correct API endpoint (e.g., https://api.semantria.com/v2.0/app/documents.json for queueing documents).
• Inspect Request Body: Ensure your JSON request body is valid and adheres to the expected structure specified in the Semantria API reference. Incorrect formatting can lead to parsing errors.
• Network Connectivity: Verify your application has internet access and can reach api.semantria.com. Firewall or proxy settings might interfere.
• Check Semantria Status: Occasionally, service outages can occur. Check the Semantria status page (if available, otherwise Lexalytics/InMoment support channels) for any reported issues.
• Consult Documentation and Support: The Semantria Help Portal contains detailed documentation, FAQs, and troubleshooting guides. If issues persist, contact Semantria support for assistance.