# Primenza SDKs

Official client libraries for the Primenza Enterprise API.

| Language | File |
|----------|------|
| PHP | [primenza-php-sdk.php](primenza-php-sdk.php) |
| JavaScript | [primenza-js-sdk.js](primenza-js-sdk.js) |
| Python | [primenza-python-sdk.py](primenza-python-sdk.py) |
| Go | [primenza-go-sdk.go](primenza-go-sdk.go) |
| Java | [primenza-java-sdk.java](primenza-java-sdk.java) |
| C# | [primenza-csharp-sdk.cs](primenza-csharp-sdk.cs) |

## Authentication

All requests require an API key:

```
Authorization: Bearer pz_your_api_key
```

Create API keys in **Settings → API Keys**.

## Response Envelope

All REST endpoints return:

```json
{
  "data": { ... },
  "meta": {},
  "errors": []
}
```

SDKs automatically unwrap `data` and throw on `errors`. Permission errors include `meta.required` and `meta.granted`.

### Error example (403)

```json
{
  "data": null,
  "meta": { "required": "audits", "granted": ["read"] },
  "errors": [{ "message": "Insufficient API key permissions" }]
}
```

## Rate Limits

- **API**: 120 requests/minute per API key
- **Agent**: 30 requests/minute per agent token

## GraphQL

Standard GraphQL API powered by `webonyx/graphql-php` with field selection support:

```
POST /api/v1/graphql
{ "query": "query { domains { id name url } }", "variables": {} }
```

**Queries:** `domains`, `domain(id)`, `dashboard(domainId)`, `audits(domainId)`, `monitoring(domainId)`, `seo`, `geo`, `ai_visibility`, `performance`, `links`, `competitors`, `content_gaps`, `citation`, `knowledge_graph`, `schema`, `reports`, `agents`, `deploy`

**Mutations:** `crawl`, `runFullAudit`, `runSeo`, `runGeo`, `runAiVisibility`, `runPerformance`, `runLinks`, `discoverContentGaps`, `addCompetitor`, `buildKnowledgeGraph`, `deployRobots`, `generateSchema`, `deploySchema`

Pass arguments explicitly, e.g. `query($id: ID!) { seo(domainId: $id) { audit { overall_score } } }`.

## Data accuracy & fallbacks

| Integration | Env variable | Without key |
|-------------|--------------|-------------|
| Performance | `PAGESPEED_API_KEY` | HTTP measurements (`http_measurements`) |
| Backlinks | `BACKLINK_API_KEY` | Crawl signals (`crawl_signals`) |
| AI content | `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` | Rules/templates (`ai_or_fallback`) |

Metrics are always computed — badges in the UI show the active data source.

SDKs wrap the full tenant + domain API surface (~86 endpoints). All six official SDKs (JS, PHP, Python, Go, Java, C#) expose tenant admin, domain lifecycle, audits, deploy, agents, content gaps, schema, and `PrimenzaAgentClient` for agent poll/report. See [OpenAPI](/openapi.yaml) for the canonical route catalog.

## Performance & Link Health

```javascript
const client = new PrimenzaClient('pz_your_api_key');
const perf = await client.performance(domainId);
const links = await client.links(domainId);
await client.runPerformance(domainId);
await client.runLinks(domainId);
```

```python
client = PrimenzaClient("pz_your_api_key")
client.performance(domain_id)
client.run_links(domain_id)
```

## REST Endpoints

See the [Developer Portal](/developers) or [OpenAPI spec](/openapi.yaml) for the full endpoint catalog.

## Billing

| Method | Path | Description |
|--------|------|-------------|
| GET | `/billing` | Current plan, usage, and limits |
| POST | `/billing/checkout` | Create Stripe checkout (`plan`, optional URLs) |
| POST | `/billing/portal` | Open Stripe customer portal |

Billing mutations require a write-capable API key. Live checkout needs `STRIPE_SECRET`.

## Schema analysis

| Method | Path | Description |
|--------|------|-------------|
| POST | `/domains/{id}/schema/analyze` | Queue a schema analysis audit |

Outbound webhooks include `X-Primenza-Signature: sha256=...` (HMAC of the raw JSON body).