---
title: "Documentation — MediaShare"
description: "Everything you need to build, integrate, and deploy against MediaShare APIs."
---

# Documentation

Everything you need to build, integrate, and deploy against MediaShare APIs.

## Getting Started

Connect to MediaShare services in three steps via REST, MCP, or Agent Skills.

### 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:

```text
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.

```bash
# 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"
```

## Architecture & Principles

Core architectural decisions and operating constraints across all MediaShare services.

### 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.

> OpenAPI specifications are hosted at /openapi.json on each service domain.

### 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.

## Authentication & Quotas

API keys, headers, and rate limiting policies.

### API Key Authentication

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

> Never commit API keys into version control or expose them in client-side frontends.

```http
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:

```text
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
```

## Security & SSRF Baseline

Defenses, bounded fetching, and privacy policies for data-fetching services.

### 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.