Organizations

The Developer API key carries an organization scope. Every endpoint operates on that org — there is no cross-org access from a single key. Use these endpoints to read org metadata, manage members, and handle invites.

Every example below shows the Python SDK call and the equivalent raw REST request. The REST examples authenticate with an X-API-Key header; set PICTOGRAPH_API_KEY in your shell to copy-and-run them.

from pictograph import Client
client = Client()  # reads PICTOGRAPH_API_KEY

me

Fetch the active organization (the one the API key belongs to).

org = client.organizations.me()
print(org.id, org.name, org.subscription_tier, org.member_count)

curl -s "https://api.pictograph.io/api/v1/developer/organizations/me" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns Organization with tier (free / core / pro / team), monthly compute allowance, member and pending-invite counts, and usage limits.

list_members

List every member of the org with role and email.

for m in client.organizations.list_members():
    print(m.email, m.role, m.joined_at)

curl -s "https://api.pictograph.io/api/v1/developer/organizations/members" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns list[OrganizationMember].

update_member_role

Promote / demote a member. member_id is the membership row’s UUID, not the underlying user UUID.

Arg	Type	Default	Notes
member_id	str	required	Membership row UUID
role	str	required	viewer / member / admin / owner

client.organizations.update_member_role(
    member_id="member-uuid",
    role="admin",     # viewer / member / admin / owner
)

curl -s -X PATCH "https://api.pictograph.io/api/v1/developer/organizations/members/member-uuid" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

The last owner of an organization cannot be demoted.

remove_member

Remove a member from the org. The user’s account is preserved — only the org membership is revoked. They can be re-invited.

client.organizations.remove_member(member_id="member-uuid")

curl -s -X DELETE "https://api.pictograph.io/api/v1/developer/organizations/members/member-uuid" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

The last owner of an organization cannot be removed.

list_invites

List invites in the org. Filter by status ∈ {"pending", "accepted", "revoked", "expired"}, or omit it for all statuses.

invites = client.organizations.list_invites(status="pending")
for inv in invites:
    print(inv.email, inv.role, inv.expires_at)

curl -s "https://api.pictograph.io/api/v1/developer/organizations/invites?status=pending" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns list[OrganizationInvite].

invite

Invite a new member by email. The invite token is delivered via email and is not returned in the response — invitees follow the email link.

Arg	Type	Default	Notes
email	str	required	Lowercased + trimmed server-side
role	str	"member"	admin / member / viewer. Owners must be promoted post-acceptance

invite = client.organizations.invite(
    email="new@example.com",
    role="member",
)
print(invite.email, invite.status)

curl -s -X POST "https://api.pictograph.io/api/v1/developer/organizations/invites" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "new@example.com", "role": "member"}'

Returns OrganizationInvite with status "pending". The member cap counts existing members plus pending invites against the org’s tier limit.

revoke_invite

Revoke a pending invite immediately. No-op if the invite is already accepted or expired.

client.organizations.revoke_invite(invite_id="invite-uuid")

curl -s -X DELETE "https://api.pictograph.io/api/v1/developer/organizations/invites/invite-uuid" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Permission matrix

Op	Min role
me, list_members, list_invites	viewer
update_member_role, invite, revoke_invite	admin
remove_member	admin (can’t remove the last owner)

Common errors

Status	Exception	Cause
403	ForbiddenError	Caller’s role too low for the action
404	NotFoundError	member_id / invite_id doesn’t exist (or belongs to another org)
402	PaymentRequiredError	Member cap (members + pending invites) reached for the tier
409	ConflictError	invite to an email that’s already a member or has a pending invite
422	ValidationError	Invalid role, malformed email