HTTP API v1 & Mobile Integration

# pip install notpixel
from notpixel import AsyncAds
 
# Generates 384-dimensional embeddings locally (BAAI/bge-small-en-v1.5).
ads = AsyncAds(publisher_id="pub_10565", cache=True)
 
async def handle_chat(prompt: str) -> dict:
    # Runs your LLM and contextual ad selection in parallel (best-effort)
    result = await ads.respond(
        input=prompt,
        llm=lambda: call_your_llm(prompt),
    )
    return {
        "text": result.text,
        "ad": result.ad.to_dict() if result.ad else None,
    }

import uuid
import httpx
import asyncio
from notpixel import generate_local_embedding, sanitize_and_truncate
 
NOTPIXEL_BASE_URL = "https://api.notpixel.ai"
PUBLISHER_ID = "pub_10565"
 
async def pick_contextual_ad(prompt: str, lang: str = "pt") -> dict | None:
    request_id = f"req_{uuid.uuid4().hex}"
    local = await asyncio.to_thread(generate_local_embedding, sanitize_and_truncate(prompt))
    async with httpx.AsyncClient(timeout=1.5) as client:
        resp = await client.post(
            f"{NOTPIXEL_BASE_URL}/api/v1/pick",
            json={
                "publisherId": PUBLISHER_ID,
                "requestId": request_id,
                "embedding": local.embedding,
                "context": {"lang": lang},
            },
        )
        resp.raise_for_status()
        data = resp.json()
        if not data.get("ad"):
            return None
        return {
            "impressionId": data["impressionId"],
            "requestId": data["requestId"],
            "ad": data["ad"],
        }

import uuid
import httpx
import asyncio
from notpixel import generate_local_embedding, sanitize_and_truncate
 
# Generate a compatible vector locally with the Python SDK helper.
 
async def pick_ad_private(prompt: str) -> dict | None:
    result = await asyncio.to_thread(generate_local_embedding, sanitize_and_truncate(prompt))
    vector = result.embedding
    async with httpx.AsyncClient(timeout=1.5) as client:
        resp = await client.post(
            "https://api.notpixel.ai/api/v1/pick",
            json={
                "publisherId": "pub_10565",
                "requestId": f"req_{uuid.uuid4().hex}",
                "embedding": vector,
            },
        )
        resp.raise_for_status()
        data = resp.json()
        return data if data.get("ad") else None

package notpixel
 
import (
	"bytes"
	"context"
	"encoding/json"
	"net/http"
	"time"
)
 
type PickRequest struct {
	PublisherID string            `json:"publisherId"`
	RequestID   string            `json:"requestId,omitempty"`
	Embedding   []float64         `json:"embedding,omitempty"`
	Context     map[string]string `json:"context,omitempty"`
}
 
type PickResponse struct {
	RequestID    string `json:"requestId"`
	ImpressionID string `json:"impressionId"`
	Ad           *struct {
		ID              string `json:"id"`
		ContentRevision int    `json:"contentRevision"`
		Headline        string `json:"headline"`
		Body            string `json:"body"`
		Disclosure      string `json:"disclosure"`
		CTA             struct {
			Label string `json:"label"`
			URL   string `json:"url"`
		} `json:"cta"`
	} `json:"ad"`
}
 
func PickAd(ctx context.Context, reqBody PickRequest) (*PickResponse, error) {
	payload, err := json.Marshal(reqBody)
	if err != nil {
		return nil, err
	}
	client := &http.Client{Timeout: 1500 * time.Millisecond}
	req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.notpixel.ai/api/v1/pick", bytes.NewReader(payload))
	if err != nil {
		return nil, err
	}
	req.Header.Set("Content-Type", "application/json")
 
	resp, err := client.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
 
	var out PickResponse
	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
		return nil, err
	}
	return &out, nil
}

# embedding.json must contain all 384 values generated locally.
# 1. Pick a contextual ad
curl -sS -X POST https://api.notpixel.ai/api/v1/pick \
  -H "Content-Type: application/json" \
  -d "$(jq -n --slurpfile vector embedding.json \
    '{publisherId: "pub_10565", requestId: "req_demo_001", embedding: $vector[0], context: {lang: "en"}}')"
 
# 2. Track click on the returned impressionId
curl -sS -X POST https://api.notpixel.ai/api/v1/click \
  -H "Content-Type: application/json" \
  -d '{
    "impressionId": "550e8400-e29b-41d4-a716-446655440000",
    "metadata": { "source": "cli_test" }
  }'

import Ads, { type Ad } from '@notpixel/react-native/local';
import { AdCard } from '@notpixel/react-native/react';
 
const ads = new Ads({ publisherId: 'YOUR_PUBLISHER_ID' });
 
// Render an ad received from your existing backend with native tracking.
export function MobileAd({ ad, impressionId }: {
  ad: Ad;
  impressionId: string;
}) {
  return <AdCard ad={ad} impressionId={impressionId} client={ads} />;
}

import Foundation
 
actor NotPixelMobileTracker {
    private let baseURL = URL(string: "https://api.notpixel.ai")!
    private var trackedImpressions = Set<String>()
 
    func trackImpression(impressionId: String) async {
        guard !trackedImpressions.contains(impressionId) else { return }
        trackedImpressions.insert(impressionId)
        await post(path: "/api/v1/events", body: ["impressionId": impressionId])
    }
 
    func trackClick(impressionId: String) async {
        await post(
            path: "/api/v1/click",
            body: [
                "impressionId": impressionId,
                "metadata": ["platform": "ios"]
            ]
        )
    }
 
    private func post(path: String, body: [String: Any]) async {
        var request = URLRequest(url: baseURL.appendingPathComponent(path))
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.httpBody = try? JSONSerialization.data(withJSONObject: body)
        _ = try? await URLSession.shared.data(for: request)
    }
}

package ai.notpixel.tracker
 
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import org.json.JSONObject
import java.net.HttpURLConnection
import java.net.URL
import java.util.concurrent.ConcurrentHashMap
 
object NotPixelTracker {
    private const val BASE_URL = "https://api.notpixel.ai"
    private val trackedImpressions = ConcurrentHashMap.newKeySet<String>()
 
    suspend fun trackImpression(impressionId: String) {
        if (!trackedImpressions.add(impressionId)) return
        post("/api/v1/events", JSONObject().put("impressionId", impressionId))
    }
 
    suspend fun trackClick(impressionId: String) {
        val payload = JSONObject()
            .put("impressionId", impressionId)
            .put("metadata", JSONObject().put("platform", "android"))
        post("/api/v1/click", payload)
    }
 
    private suspend fun post(path: String, json: JSONObject) = withContext(Dispatchers.IO) {
        runCatching {
            val conn = (URL("$BASE_URL$path").openConnection() as HttpURLConnection).apply {
                requestMethod = "POST"
                connectTimeout = 3000
                readTimeout = 3000
                doOutput = true
                setRequestProperty("Content-Type", "application/json")
            }
            conn.outputStream.use { it.write(json.toString().toByteArray()) }
            conn.responseCode
            conn.disconnect()
        }
    }
}