Skip to main content

​
Prerequisites

Before you begin, ensure you have:
  • Access to the LoopOS AI Server (production, staging, or development environment)
  • An HTTP client (curl, Postman, or your preferred tool)
  • Basic understanding of REST APIs and JSON

​
Base URL

LoopOS AI Server is deployed across multiple environments: 
https://loopos-ai-server-3recw.ondigitalocean.app

​
Your First API Call

Let’s start with a simple example using the Decision service, which helps make choices based on context.

​
Example: Decision Service

The Decision service picks the best choice from a list of options given a prompt and context. 
curl -X POST "https://loopos-ai-server-3recw.ondigitalocean.app/loopos_ai_decision" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "PT-PT",
    "prompt": "What condition best describes this item?",
    "options": ["Excellent", "Good", "Fair", "Poor"],
    "item_context": "iPhone 12 with minor scratches",
    "context": "Assessing item condition for marketplace listing"
  }'

​
Expected Response

{
  "decision": "Good",
  "reasoning": "Based on the description of minor scratches, the item is in good condition. While not excellent, it shows only light wear and remains fully functional."
}

​
Common Request Fields

Most LoopOS AI services share common input fields:
FieldTypeDescriptionDefault
languagestringLanguage code (e.g., “PT-PT”, “en-US”)“PT-PT”
conversationbooleanWhether this is part of a conversation threadfalse
callback_urlstringOptional callback URL for async responsesnull
loopos_core_contextstringBusiness context for the AI agentnull
messagesarrayList of conversation messages[]
imagesarrayImage URLs or base64 data URLs[]
agent_specificobjectService-specific parametersnull
session_extra_dataobjectAdditional session metadata

​
Example: Chat with Submission Agent

The Submission service provides a conversational interface for product submission: 
curl -X POST "https://loopos-ai-server-3recw.ondigitalocean.app/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "PT-PT",
    "messages": [
      {"role": "user", "text": "Quero vender um iPhone 12"}
    ],
    "images": [],
    "conversation": true,
    "session_id": "my-session-123"
  }'

​
Example: C2C Descriptor with Images

Generate a marketplace listing from images and context: 
curl -X POST "https://loopos-ai-server-3recw.ondigitalocean.app/loopos_ai_c2c_descriptor" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "PT-PT",
    "images": ["https://example.com/item-photo.jpg"],
    "agent_specific": {
      "category_name": "Electronics",
      "product_name": "iPhone 12 Pro",
      "brand_name": "Apple",
      "user_description": "iPhone em excelente estado"
    }
  }'

​
Error Handling

LoopOS AI services return standard HTTP status codes:
  • 200 OK: Request successful
  • 422 Validation Error: Invalid input parameters
  • 413 Payload Too Large: Request exceeds size limits
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server-side error
Example error response: 
{
  "detail": [
    {
      "loc": ["body", "agent_specific", "category"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​
Next Steps

1

Explore Services

Check out the Services documentation to see all available capabilities.
2

Read API Reference

Visit the API Reference for detailed endpoint documentation.
3

Learn Integration Patterns

See the AI Hub for integration guides and best practices.
4

Understand Architecture

Read about the Architecture to understand how services work internally.
For production use, always include proper error handling, retry logic, and timeout management. Consider using async processing for long-running operations.