Quickstart

Dieser Quickstart führt dich von einem API Key zu einem geprüften CSV-Export. Du erstellst eine kleine leads.csv, lädst sie als dauerhaftes Dataset hoch, definierst ein wiederverwendbares Job Spec, startest einen begrenzten Sample Run, prüfst das Ergebnis und exportierst erst nach Review.

Die API ist Raw HTTP. Die TypeScript- und Python-Beispiele unten nutzen fetch und requests; sie sind keine SDK-Beispiele.

Workflow

Voraussetzungen

Du brauchst:

• Einen Everyn API Key mit datasets:write, datasets:read, job_specs:write, job_specs:read, runs:write, runs:read, exports:write und exports:read.
• curl und jq für den kanonischen Copy-paste-Pfad.
• Optional: Node.js 18 oder neuer für die TypeScript-fetch-Beispiele.
• Optional: Python 3 mit installiertem requests für die Python-Beispiele.

Erstelle die Sample-CSV lokal:

cat > leads.csv <<'CSV'
company,website,industry,employee_count,region,notes
Northstar Robotics,https://northstar.example,Manufacturing,420,North America,Looking for automated QA on production lines
Lumen Health,https://lumen.example,Healthcare,180,Europe,Expanding clinical operations across two countries
Atlas Freight,https://atlas.example,Logistics,760,North America,Interested in lane optimization and shipment visibility
CSV

Setze Shell-Variablen für diese Terminal-Session. Lege echte API Keys nicht in .env-Dateien oder Source Control ab.

export EVERYN_BASE_URL="https://api.geteveryn.com"
export EVERYN_API_KEY="sk-everyn-..."

Die TypeScript- und Python-Snippets erwarten dieselben Umgebungsvariablen im Prozess.

1. Authentifizierung prüfen

Liste runnable Models, bevor du ein Job Spec erstellst.

curl -sS "$EVERYN_BASE_URL/v1/models" \
  -H "Authorization: Bearer $EVERYN_API_KEY"

Erfolgreiche Antworten enthalten ein data-Array mit Model Records. Wenn du 401 oder 403 erhältst, korrigiere den Key vor dem Weiterarbeiten. Siehe Authentifizierung, API-Fehler und die Models API-Referenz.

2. CSV-Dataset hochladen

Erstelle einen Dataset Upload mit einem Idempotency Key. Verwende denselben Key nur dann erneut, wenn du dieselbe Anfrage nach einem Timeout wiederholst.

UPLOAD_RESPONSE=$(curl -sS -X POST "$EVERYN_BASE_URL/v1/dataset-uploads" \
  -H "Authorization: Bearer $EVERYN_API_KEY" \
  -H "Idempotency-Key: upload-leads-001" \
  -F "sourceType=csv" \
  -F "sourceName=leads.csv" \
  -F 'metadata={"purpose":"quickstart"}' \
  -F "file=@./leads.csv;type=text/csv")

echo "$UPLOAD_RESPONSE" | jq
UPLOAD_ID=$(echo "$UPLOAD_RESPONSE" | jq -r '.id')

Erwarteter erfolgreicher Upload-Response-Ausschnitt:

{
  "id": "upl_...",
  "status": "processing",
  "datasetId": null,
  "failure": null
}

Warte, bis Intake abgeschlossen ist. Diese Schleife beendet sich bei completed, bricht bei failed oder expired sofort ab und timed nach ungefähr einer Minute aus.

DATASET_ID=""

for attempt in $(seq 1 30); do
  UPLOAD_RESPONSE=$(curl -sS "$EVERYN_BASE_URL/v1/dataset-uploads/$UPLOAD_ID" \
    -H "Authorization: Bearer $EVERYN_API_KEY")
  STATUS=$(echo "$UPLOAD_RESPONSE" | jq -r '.status')

  if [ "$STATUS" = "completed" ]; then
    DATASET_ID=$(echo "$UPLOAD_RESPONSE" | jq -r '.datasetId')
    break
  fi

  if [ "$STATUS" = "failed" ] || [ "$STATUS" = "expired" ]; then
    echo "$UPLOAD_RESPONSE" | jq '.failure'
    exit 1
  fi

  sleep 2
done

if [ -z "$DATASET_ID" ]; then
  echo "Timed out waiting for dataset upload $UPLOAD_ID"
  exit 1
fi

echo "DATASET_ID=$DATASET_ID"

Erwarteter abgeschlossener Upload-Ausschnitt:

{
  "id": "upl_...",
  "status": "completed",
  "datasetId": "ds_...",
  "failure": null
}

Wenn der Upload fehlschlägt, prüfe failure.code, failure.docsUrl und failure.fieldErrors. Siehe Dataset Uploads und die Dataset Uploads API-Referenz.

3. Job Spec erstellen

Ein Job Spec ist der wiederverwendbare Arbeitsvertrag für zukünftige Runs. Dieses Beispiel bewertet jede Company gegen ein Zielkundenprofil.

JOB_SPEC_RESPONSE=$(curl -sS -X POST "$EVERYN_BASE_URL/v1/job-specs" \
  -H "Authorization: Bearer $EVERYN_API_KEY" \
  -H "Idempotency-Key: job-lead-fit-001" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "Lead fit scoring",
    "description": "Score leads against the target ICP.",
    "mode": "add_columns",
    "prompt": "Score each company for ICP fit. Return a score, reason, and confidence.",
    "model": "openai:gpt-5.4-mini",
    "outputSchema": {
      "columns": [
        {
          "name": "fit_score",
          "type": "integer",
          "description": "Score from 1 to 5.",
          "minimum": 1,
          "maximum": 5
        },
        {
          "name": "fit_reason",
          "type": "string",
          "description": "Concise explanation."
        },
        {
          "name": "confidence",
          "type": "number",
          "description": "Confidence from 0 to 1.",
          "minimum": 0,
          "maximum": 1
        }
      ]
    }
  }')

echo "$JOB_SPEC_RESPONSE" | jq
JOB_SPEC_ID=$(echo "$JOB_SPEC_RESPONSE" | jq -r '.id')

Erwarteter Response-Ausschnitt:

{
  "id": "js_...",
  "name": "Lead fit scoring",
  "currentVersionId": "jsv_...",
  "version": {
    "mode": "add_columns",
    "model": "openai:gpt-5.4-mini",
    "outputSchema": {
      "columns": [
        { "name": "fit_score" },
        { "name": "fit_reason" },
        { "name": "confidence" }
      ]
    }
  }
}

Wenn Model-Validation fehlschlägt, wähle ein runnable Model aus /v1/models. Siehe Job Specs und die Job Specs API-Referenz.

4. Sample Run erstellen und starten

Starte mit einem begrenzten Run, bevor größerer Spend freigegeben wird. Der limit Scope hält diesen Sample begrenzt, selbst wenn das Dataset später wächst.

RUN_RESPONSE=$(curl -sS -X POST "$EVERYN_BASE_URL/v1/runs" \
  -H "Authorization: Bearer $EVERYN_API_KEY" \
  -H "Idempotency-Key: run-preview-001" \
  -H "Content-Type: application/json" \
  --data "{
    \"datasetId\": \"$DATASET_ID\",
    \"jobSpecId\": \"$JOB_SPEC_ID\",
    \"scope\": { \"type\": \"limit\", \"count\": 3 }
  }")

echo "$RUN_RESPONSE" | jq
RUN_ID=$(echo "$RUN_RESPONSE" | jq -r '.id')

curl -sS -X POST "$EVERYN_BASE_URL/v1/runs/$RUN_ID/start" \
  -H "Authorization: Bearer $EVERYN_API_KEY" | jq

Erwarteter Run-Response-Ausschnitt:

{
  "id": "run_...",
  "state": "queued",
  "rowCounts": {
    "total": 3,
    "processed": 0,
    "failed": 0
  }
}

Wenn Start für einen queued oder running Run wiederholt wird, kommt der bestehende Run zurück und es darf keine doppelte Runner-Arbeit entstehen.

Warte, bis der Sample Run einen terminalen Zustand erreicht:

TERMINAL_STATE=""

for attempt in $(seq 1 60); do
  RUN_RESPONSE=$(curl -sS "$EVERYN_BASE_URL/v1/runs/$RUN_ID" \
    -H "Authorization: Bearer $EVERYN_API_KEY")
  STATE=$(echo "$RUN_RESPONSE" | jq -r '.state')

  case "$STATE" in
    succeeded|completed_with_flags|failed|canceled)
      TERMINAL_STATE="$STATE"
      break
      ;;
  esac

  sleep 2
done

if [ -z "$TERMINAL_STATE" ]; then
  echo "Timed out waiting for run $RUN_ID"
  exit 1
fi

echo "$RUN_RESPONSE" | jq '{id, state, rowCounts}'

succeeded ist der saubere Pfad. completed_with_flags ist der Inspect-and-decide-Pfad. Behandle failed und canceled als Stop-and-debug-Zustände. Siehe Runs und die Runs API-Referenz.

5. Vor größerem Scope prüfen

Prüfe Rows, Events, Outputs, Failures und aufgelöste Retry-Lineage-Ergebnisse:

curl -sS "$EVERYN_BASE_URL/v1/runs/$RUN_ID/rows?limit=50" \
  -H "Authorization: Bearer $EVERYN_API_KEY" | jq

curl -sS "$EVERYN_BASE_URL/v1/runs/$RUN_ID/events?type=row.failed" \
  -H "Authorization: Bearer $EVERYN_API_KEY" | jq

curl -sS "$EVERYN_BASE_URL/v1/runs/$RUN_ID/outputs" \
  -H "Authorization: Bearer $EVERYN_API_KEY" | jq

curl -sS "$EVERYN_BASE_URL/v1/runs/$RUN_ID/failures" \
  -H "Authorization: Bearer $EVERYN_API_KEY" | jq

curl -sS "$EVERYN_BASE_URL/v1/runs/$RUN_ID/resolved-results" \
  -H "Authorization: Bearer $EVERYN_API_KEY" | jq

Review-Checkliste:

• Der Run ist terminal: succeeded oder completed_with_flags.
• rowCounts.processed entspricht der ausgeführten Sample-Größe.
• Generierte Felder passen zum outputSchema: fit_score, fit_reason und confidence.
• Fehlgeschlagene oder geflaggte Rows haben verständliche failure.code, failure.message und failure.docsUrl.
• Prompt, Model, Schema und Review-Kriterien sind gut genug, bevor du einen größeren Run erstellst.

Exportiere erst, nachdem diese Checkliste bestanden ist.

6. Retry oder Revision

Retrye unaufgelöste Rows aus einem terminalen Run, wenn dieselbe gepinnte Job-Spec-Version weiterhin korrekt ist:

RETRY_RESPONSE=$(curl -sS -X POST "$EVERYN_BASE_URL/v1/runs/$RUN_ID/retry" \
  -H "Authorization: Bearer $EVERYN_API_KEY" \
  -H "Idempotency-Key: retry-run-001")

echo "$RETRY_RESPONSE" | jq

Überarbeite das Job Spec und führe einen neuen begrenzten Sample aus, wenn Prompt, Model, Mode, Output Schema oder Review-Kriterien geändert werden müssen. Retry ist für Ausführungsprobleme; Revision ist für Product-Contract-Probleme.

7. Geprüfte Ergebnisse exportieren

Erstelle einen self-starting CSV-Export aus dem geprüften Run.

EXPORT_RESPONSE=$(curl -sS -X POST "$EVERYN_BASE_URL/v1/runs/$RUN_ID/exports" \
  -H "Authorization: Bearer $EVERYN_API_KEY" \
  -H "Idempotency-Key: export-results-001" \
  -H "Content-Type: application/json" \
  --data '{ "type": "generated_outputs", "format": "csv", "fileName": "results.csv" }')

echo "$EXPORT_RESPONSE" | jq
EXPORT_ID=$(echo "$EXPORT_RESPONSE" | jq -r '.id')

Erwarteter Export-Response-Ausschnitt:

{
  "id": "exp_...",
  "status": "ready",
  "downloadReady": true,
  "downloadUrl": "/v1/exports/exp_.../download",
  "failure": null
}

Wenn der Export nicht sofort ready ist, polle ihn vor dem Download:

for attempt in $(seq 1 30); do
  EXPORT_RESPONSE=$(curl -sS "$EVERYN_BASE_URL/v1/exports/$EXPORT_ID" \
    -H "Authorization: Bearer $EVERYN_API_KEY")
  STATUS=$(echo "$EXPORT_RESPONSE" | jq -r '.status')

  if [ "$STATUS" = "ready" ]; then
    break
  fi

  if [ "$STATUS" = "failed" ] || [ "$STATUS" = "expired" ]; then
    echo "$EXPORT_RESPONSE" | jq '.failure'
    exit 1
  fi

  sleep 2
done

if [ "$STATUS" != "ready" ]; then
  echo "Timed out waiting for export $EXPORT_ID"
  exit 1
fi

curl -sS "$EVERYN_BASE_URL/v1/exports/$EXPORT_ID/download" \
  -H "Authorization: Bearer $EVERYN_API_KEY" \
  -o results.csv

Siehe Exports API-Referenz für Exporttypen und Download-Verhalten.

Troubleshooting

Nächste Schritte

• Lies Konzepte für das dauerhafte Objektmodell.
• Lies Datasets, Job Specs und Runs für Produktverhalten.
• Nutze die generierte API-Referenz, wenn du Clients auf Endpoint-Ebene implementierst.