C.O.G.N.I.T.

Version 4.0.0

Overview

The C.O.G.N.I.T. (Cognitive Network for Image & Text Modeling) API provides programmatic access to the research platform. This RESTful API allows you to integrate image description tasks into your applications and manage submissions.

Version

4.0.0

Base URL

/api

Security

Rate Limiting: Default: 200 requests per day, 50 per hour
Authentication: None required for participant endpoints - participants are identified by participant_id and session_id
Data Protection: IP addresses are hashed (SHA-256) for privacy

Features

Image Management: Fetch random images for normal, survey, and attention tasks
Data Submission: Submit participant responses with descriptions, ratings, and feedback
Health Monitoring: Check system connectivity and service status
Security: Rate limiting and hardened security headers

Quick Start

Make your first request to /api/images/random
Submit participant data via /api/submit
Retrieve submissions via /api/submissions/<participant_id>

API Endpoints

Public Endpoints

GET /api/health ▶

Check system health and connectivity status

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00Z",
  "services": {
    "database": "connected",
    "images": "accessible"
  }
}

POST /api/participants ▶

Create a new participant record with user details

Rate Limit: 30 per minute

Request Body

{
  "participant_id": "string (required)",
  "session_id": "string (required)",
  "username": "string (required)",
  "email": "string (optional)",
  "phone": "string (optional)",
  "gender": "string (required)",
  "age": "integer (required)",
  "place": "string (required)",
  "native_language": "string (required)",
  "prior_experience": "string (required)"
}

Response

{
  "status": "success",
  "participant_id": "uuid-string",
  "message": "Participant created successfully"
}

GET /api/participants/{participant_id} ▶

Get participant details

{
  "participant_id": "uuid-string",
  "username": "john_doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "gender": "male",
  "age": 25,
  "place": "New York",
  "native_language": "English",
  "prior_experience": "Photography",
  "consent_given": true,
  "created_at": "2024-01-01T00:00:00Z"
}

POST /api/consent ▶

Record participant consent

Rate Limit: 20 per minute

Request Body

{
  "participant_id": "string (required)",
  "consent_given": "boolean (required)"
}

Response

{
  "status": "success",
  "message": "Consent recorded successfully",
  "timestamp": "2024-01-01T00:00:00Z"
}

GET /api/consent/{participant_id} ▶

Get consent status for a participant

{
  "participant_id": "uuid-string",
  "consent_given": true,
  "consent_timestamp": "2024-01-01T00:00:00Z"
}

GET /api/images/random ▶

Retrieve a random image for the study

Response

{
  "image_id": "aurora-lake.svg",
  "image_url": "/api/images/aurora-lake.svg"
}

GET /api/images/{image_id} ▶

Serve a specific image file

Parameters

Name	Type	Required	Description
`image_id`	string	Yes	ID of the image to retrieve

Response

Binary image data

POST /api/submit ▶

Submit participant response data (requires prior consent)

Rate Limit: 60 per minute

Request Body

{
  "participant_id": "string (required)",
  "session_id": "string (required)",
  "image_id": "string (required)",
  "description": "string (required, min 60 words)",
  "rating": "integer (required, 1-10)",
  "feedback": "string (required, min 5 chars)",
  "time_spent_seconds": "number (required)",
  "is_survey": "boolean"
}

Attention checks are determined server-side based on the image ID. The response only includes attention_passed when applicable.

Response

{
  "status": "ok",
  "word_count": 45,
  "attention_passed": true
}

GET /api/submissions/{participant_id} ▶

Get all submissions for a participant

Response

[{...submission objects...}]

GET /api/security/info ▶

Get security configuration details

{
  "security": {
    "rate_limits": "object",
    "cors_allowed_origins": "array",
    "security_headers": "array"
  }
}

GET /api/docs ▶

Retrieve the API documentation

Response

Documentation payload

Code Examples

JavaScript / Fetch

// Check system health
const healthResponse = await fetch('/api/health');
const health = await healthResponse.json();
console.log(health.status); // 'healthy' or 'degraded'

// Get a random image
const response = await fetch('/api/images/random');
const image = await response.json();
console.log(image.image_url);

// Submit participant data
const submission = {
  participant_id: 'user-123',
  session_id: 'session-456',
  image_id: 'aurora-lake.svg',
  description: 'The image shows a beautiful sunset over mountains...',
  rating: 8,
  feedback: 'Interesting image',
  time_spent_seconds: 45
};

const submitResponse = await fetch('/api/submit', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(submission)
});

const result = await submitResponse.json();
console.log(result.status); // 'ok'

Python / Requests

import requests

# Check system health
health_response = requests.get('http://localhost:5000/api/health')
health = health_response.json()
print(health['status'])  # 'healthy' or 'degraded'

# Get a random image
response = requests.get('http://localhost:5000/api/images/random')
image = response.json()
print(image['image_url'])

# Submit participant data
submission = {
    'participant_id': 'user-123',
    'session_id': 'session-456',
    'image_id': 'aurora-lake.svg',
    'description': 'The image shows a beautiful sunset...',
    'rating': 8,
    'feedback': 'Interesting image',
    'time_spent_seconds': 45
}

response = requests.post(
    'http://localhost:5000/api/submit',
    json=submission
)
result = response.json()
print(result['status'])  # 'ok'

cURL

# Check system health
curl -X GET "http://localhost:5000/api/health"

# Get a random image
curl -X GET "http://localhost:5000/api/images/random"

# Submit participant data
curl -X POST "http://localhost:5000/api/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "participant_id": "user-123",
    "session_id": "session-456",
    "image_id": "aurora-lake.svg",
    "description": "The image shows...",
    "rating": 8,
    "feedback": "Great image",
    "time_spent_seconds": 45
  }'

Error Handling

The API uses standard HTTP response codes to indicate the success or failure of requests.

HTTP Status Codes

Code	Meaning	Description
`200`	OK	Request succeeded
`400`	Bad Request	Invalid parameters or missing required fields
`401`	Unauthorized	Authentication required
`404`	Not Found	Resource not found
`415`	Unsupported Media Type	Request must use application/json
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server-side error

Error Response Format

{
  "error": "Description of what went wrong"
}

Common Errors

Minimum 60 words required - Description is too short
rating must be an integer between 1-10 - Invalid rating value
comments must be at least 5 characters - Feedback is too short
image_id is required - Missing required field