Documentație

1. Three ways to connect

MediaShare is designed around an API-first philosophy. Every service is an independent HTTP API, wrapped by a thin Model Context Protocol (MCP) server and documented with an agent-ready skill.

You choose how to integrate depending on your architecture:

Direct HTTP API  ──> For backend microservices, scripts, and applications
MCP Server       ──> For AI agent platforms (Claude Desktop, Cursor, Pi, Codex)
Agent Skill      ──> For prompt engineering and procedural workflow instructions

2. Making your first HTTP request

Services with public tiers (such as IP Geolocation) can be called directly without credentials. Authenticated services require a Bearer token in the standard Authorization header.

# Public lookup example
curl -X GET "https://geo.mediashare.ro/" \
  -H "Accept: application/json"

# Authenticated service example
curl -G "https://wine.mediashare.ro/api/wine/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "q=Purcari Malbec 2020"

Independent product boundaries

Each subdomain (wine.mediashare.ro, geo.mediashare.ro, etc.) is a distinct product boundary with its own runtime, monitoring, and release cadence.

We do not route traffic through a monolithic API gateway, ensuring zero single point of failure and allowing each service to evolve independently.

OpenAPI 3.1 is canonical

Every service ships an OpenAPI 3.1 specification before implementation. The HTTP contract is canonical; MCP wrappers and skills are thin translation layers that never duplicate or modify business logic.

Deterministic & low maintenance

We prioritize deterministic transformations, scheduled snapshot refreshes (e.g. daily BNR market feeds), and cached responses over editorial workflows that require routine human curation.

API Key Authentication

Pass your API key as a Bearer token in the HTTP Authorization header.

GET /v1/extract HTTP/1.1
Host: meta.mediashare.ro
Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxx
Accept: application/json

Standard Response Headers

All API responses include standard tracing and rate-limiting metadata headers:

X-Request-Id:          Unique UUID for distributed request tracing
RateLimit-Limit:       Maximum allowed requests in the current window
RateLimit-Remaining:   Number of available requests remaining
RateLimit-Reset:       Unix timestamp when the rate limit window resets

SSRF Protection Layer

Services that fetch external URLs (such as meta.mediashare.ro and seo.mediashare.ro) enforce rigorous Server-Side Request Forgery (SSRF) defenses:

1. Pre-DNS resolution checks: Reject private schemes (file://, gopher://), non-standard ports, and localhost hostnames.

2. Post-DNS resolution validation: Resolve all IP addresses and verify they do not fall within RFC 1918 private ranges, loopback (127.0.0.0/8), link-local (169.254.0.0/16), or cloud metadata networks (169.254.169.254).

3. Strict timeouts (max 5s) and bounded response sizes (max 5MB) to protect against memory exhaustion and slow-loris attacks.

Data Privacy & Minimal Logging

MediaShare services log only operational telemetry (request ID, HTTP status code, latency, error classification). We do not record or retain user-submitted payloads or extracted document content by default.