API & Integrations

Oklama integrates natively with the Google Ads API to fetch search terms, classify them with AI, and apply approved keyword changes programmatically— safely and with full audit trails. Teams & Enterprise plans can request programmatic access to selected Oklama features via a private API.

Google Ads Integration

Oklama uses Google OAuth to obtain minimal scopes for the Google Ads API. We read account hierarchies (MCC, sub-accounts), ingest search term performance, and—only when you approve—apply keyword additions or negatives to the selected accounts via API.

OAuth + Minimal Scopes

OpenID/Email/Profile for login; Google Ads API scopes only.

Safe Write Operations

Changes are applied after your approval with audit logs.

MCC-Ready

Manager & sub-account structures supported out of the box.

Idempotent Jobs

Locks, retries, and dedupe to prevent duplicate actions.

Minimal API Permissions

Oklama requests only the minimum permissions necessary to function. We use the following Google API scopes:

https://www.googleapis.com/auth/adwords

Access to Google Ads data for reading search terms, metrics, and managing keywords

https://www.googleapis.com/auth/userinfo.email

Your email address for account identification and communication

https://www.googleapis.com/auth/userinfo.profile

Your basic profile information (name, profile picture) for personalization

Note: We do NOT access Gmail, Drive, Calendar, or any other Google services. You can revoke access at any time through your Google Account Permissions.

Under the Hood

Backend: FastAPI (Python 3.12), async I/O, typed models, validations
Data: MongoDB (Motor), compound indexes, schema validation
Jobs: APScheduler, distributed locks & retries, progress tracking
Caching & Controls: Redis for rate limits, circuit-breakers, and idempotency
AI: OpenAI GPT-4 with custom prompt engineering and guardrails
Observability: Structured logs, audit trails, and health checks

Security & Compliance

Tokens encrypted at rest (AES-256); TLS in transit; least-privilege access
Limited Use adherence for Google API data; no data resale or broker sharing
Role-based controls; per-action audit logs with timestamps and IDs
PBKDF2 key derivation for password hashing with bcrypt
Clear Privacy Policy and data-deletion process

Private API (Teams & Enterprise)

For qualified customers, we expose a private, authenticated API that mirrors key Oklama workflows. Typical use cases include automation, BI exports, and custom review flows.

Endpoint	Method	Purpose	Notes
/api/v1/search-terms	GET	List search terms & metrics	Filters: account, date range, classification
/api/v1/keywords	POST	Apply approved keywords/negatives	Idempotent; requires review token or role
/api/v1/jobs	GET	Retrieve job status & logs	Pagination; includes progress & timestamps
/api/v1/exports	POST	Request data export	Async; callback URL optional

Auth

Token-based (Bearer) with scoped roles; optional IP allow-lists

Rate Limits

Per-org limits with burst buffers; contact for higher quotas

Webhooks

Optional callbacks for job completion and exports

Example: GET /search-terms

GET /api/v1/search-terms?account=1234567890&classification=positive&from=2025-07-01&to=2025-07-31
Authorization: Bearer <token>

200 OK
{
  "items": [
    {
      "term": "nike running shoes",
      "account_id": "1234567890",
      "impressions": 120,
      "clicks": 8,
      "conversions": 1,
      "classification": "positive",
      "confidence": 0.82,
      "last_seen": "2025-07-08T10:15:00Z"
    }
  ],
  "next_page": null
}

Example: POST /keywords

POST /api/v1/keywords
Authorization: Bearer <token>
Content-Type: application/json

{
  "account_id": "1234567890",
  "actions": [
    { 
      "type": "add_positive", 
      "keyword": "+nike +running +shoes", 
      "match_type": "BROAD" 
    },
    { 
      "type": "add_negative", 
      "keyword": "free", 
      "match_type": "PHRASE" 
    }
  ],
  "review_token": "rvw_abc123"  
}

202 Accepted
{
  "job_id": "job_7fb2e9",
  "status": "queued"
}

Need programmatic access?

We provide private API keys for Teams & Enterprise customers. Tell us about your use case and data needs.

Private API terms, quotas, and endpoints are subject to change. SLA available for eligible plans.