Zum Inhalt springen
Sursa Developers

GET/v1/users

Benutzer der Organisation auflisten

list_users

Administratoren erhalten die vollständige Liste. Jeder angemeldete Benutzer kann die Kurzliste abrufen (brief=1: ID, Name, Rolle), zum Beispiel, um eine verantwortliche Person auszuwählen. Eine Anfrage der vollständigen Liste ohne die Administratorrolle ergibt 403.

Authentifizierung

Senden Sie einen API-Schlüssel im Header Authorization: Authorization: Bearer <Schlüssel>.

Query-Parameter

  • briefboolean

    true gibt die Kurzliste zurück (ID, Login, Rolle, Name), um eine verantwortliche Person oder Reviewer auszuwählen. Für alle Rollen verfügbar.

    Standard: false

  • limitinteger

    Seitengröße. Ohne limit und cursor wird die gesamte Liste zurückgegeben; ist der Parameter angegeben, höchstens limit Einträge, und die nächste Seite steht in den Headern Link (rel="next") und X-Next-Cursor.

    ≥ 1, ≤ 200

  • cursorstring

    Cursor der nächsten Seite aus X-Next-Cursor oder next_cursor der vorherigen Antwort mit denselben Filtern; er enthält die Seitengröße. Zusammen mit offset: 422 validation.failed; ein Cursor einer anderen Liste, mit anderen Filtern oder ein fehlerhafter Cursor: 400 api.cursor_invalid.

    length ≤ 512

Header-Parameter

  • X-View-Asstring

    Nur für API-Schlüssel mit der Rolle admin. Führt die Anfrage mit dem Datenprofil <profile>[:viewer|verifier|editor] aus, zum Beispiel employee:viewer. Der Installationsschlüssel kann diesen Header nicht verwenden (403).

Cookie-Parameter

  • kb_view_asstring

    Cookie des Modus „Ansicht als“ für eine Sitzung. POST /auth/view-as setzt es, DELETE /auth/view-as entfernt es.

Antworten

200Die vollständige Liste (Administratoren) oder die Kurzliste (`brief=true`).

Antwort-Header

  • Link

    Adresse der nächsten Seite, <…>; rel="next". Fehlt der Header, ist dies die letzte Seite.

  • X-Next-Cursor

    Cursor der nächsten Seite für den Parameter cursor. Fehlt der Header, ist dies die letzte Seite.

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Eines von

401Es wurden keine Anmeldedaten gesendet (weder ein Sitzungscookie noch ein API-Schlüssel), oder der Schlüssel wurde nicht gefunden.

Antwort-Header

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

403Die Aktion ist nicht erlaubt: Die Rolle reicht nicht aus, es besteht kein Zugriff auf die Sammlung oder Karte, die Anfrage läuft im Modus „Ansicht als“, oder die Organisation ist gesperrt oder gelöscht (`detail` ist ein Objekt mit `code: org_suspended | org_deleted`).

Antwort-Header

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

422Validierungsfehler: Der Body oder die Parameter entsprechen nicht dem Schema (`detail` ist eine Liste von Validierungsfehlern), oder ein Parameterwert liegt außerhalb des zulässigen Bereichs (`detail` ist eine Meldung).

Antwort-Header

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

429Zu viele Anfragen (`api.rate_limited`), das Kontingent der Organisation für die Minute, den Tag oder den Monat ist aufgebraucht (`api.quota_exceeded`; `error.details` enthält `quota`, `limit` und `reset_at`), das Limit der Organisation ist erreicht, oder der Antwortdienst ist ausgelastet (`answers.engine_busy`). Warten Sie die im Header `Retry-After` angegebene Zeit ab.

Antwort-Header

  • Retry-After

    Anzahl der Sekunden, die Sie warten sollten, bevor Sie die Anfrage wiederholen.

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

Fehlercodes

Codes, die dieser Endpunkt in error.code zurückgeben kann, zusätzlich zu den allgemeinen Codes jeder Anfrage.

Ratenlimits

Antworten enthalten die Header RateLimit und RateLimit-Policy sowie die älteren X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Eine Antwort 429 enthält Retry-After in Sekunden: Warten Sie und versuchen Sie es dann erneut.

← users · API-Referenz