Organizations

An API key carries an organization scope. Every method here operates on that one organization and takes no organization_id parameter, so cross-org access is impossible by construction.

me

Fetch the organization the key belongs to.

Source: Organizations.me

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

pictograph organizations me

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

Returns Organization

class Organization(BaseModel):
    """Organization metadata + tier limits + credit balance."""
    id: str
    name: str
    slug: str
    description: str | None = None
    is_public: bool | None = None
    subscription_tier: Literal['free', 'core', 'pro', 'team', 'enterprise']
    credits_remaining: int
    credits_monthly_allowance: int
    credits_reset_at: datetime | None = None
    max_users: int
    max_images: int
    max_storage_bytes: int
    member_count: int
    pending_invite_count: int
    created_at: datetime
    updated_at: datetime

update

Update the organization profile. Only the fields you pass change. Requires admin or owner.

Source: Organizations.update

org = client.organizations.update(
    name="Acme Vision",
    description="Perception datasets for autonomous inspection.",
    is_public=True,
)

pictograph organizations update \
  --name "Acme Vision" \
  --description "Perception datasets for autonomous inspection." \
  --public

curl -s -X PATCH "https://api.pictograph.io/api/v1/developer/organizations/me" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Vision",
       "description": "Perception datasets for autonomous inspection.",
       "is_public": true}'

Returns Organization

class Organization(BaseModel):
    """Organization metadata + tier limits + credit balance."""
    id: str
    name: str
    slug: str
    description: str | None = None
    is_public: bool | None = None
    subscription_tier: Literal['free', 'core', 'pro', 'team', 'enterprise']
    credits_remaining: int
    credits_monthly_allowance: int
    credits_reset_at: datetime | None = None
    max_users: int
    max_images: int
    max_storage_bytes: int
    member_count: int
    pending_invite_count: int
    created_at: datetime
    updated_at: datetime

is_public controls whether the organization has a public profile page; the CLI spells it --public / --private.

list_members

Every member of the organization, with the membership row id that the role and removal calls take.

Source: Organizations.list_members

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

pictograph organizations members

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

Returns list[OrganizationMember]

class OrganizationMember(BaseModel):
    """A single member's row."""
    id: str
    user_id: str
    email: str | None = None
    full_name: str | None = None
    role: Literal['owner', 'admin', 'member', 'annotator', 'viewer']
    joined_at: datetime

update_member_role

Promote or demote a member. member_id is the membership row UUID from list_members, not the user UUID. role is owner / admin / member / viewer. The last owner cannot be demoted. Requires admin or owner.

Source: Organizations.update_member_role

client.organizations.update_member_role(
    member_id="e1f2a3b4-5c6d-4e78-9f01-a2b3c4d5e6f7",
    role="admin",
)

pictograph organizations member-role e1f2a3b4-5c6d-4e78-9f01-a2b3c4d5e6f7 --role admin

curl -s -X PATCH "https://api.pictograph.io/api/v1/developer/organizations/members/e1f2a3b4-5c6d-4e78-9f01-a2b3c4d5e6f7" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

Returns dict[str, Any]

Re-run list_members for the full row.

remove_member

Revoke a membership. The user’s account survives and they can be re-invited. The last owner cannot be removed. Requires admin or owner.

Source: Organizations.remove_member

client.organizations.remove_member(
    member_id="e1f2a3b4-5c6d-4e78-9f01-a2b3c4d5e6f7",
)

pictograph organizations member-remove e1f2a3b4-5c6d-4e78-9f01-a2b3c4d5e6f7 --yes

curl -s -X DELETE "https://api.pictograph.io/api/v1/developer/organizations/members/e1f2a3b4-5c6d-4e78-9f01-a2b3c4d5e6f7" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns None

list_invites

Filter by status (pending / accepted / expired / revoked) or omit it for all.

Source: Organizations.list_invites

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

pictograph organizations invites --status pending

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

Returns list[OrganizationInvite]

class OrganizationInvite(BaseModel):
    """A pending / accepted / expired / revoked invite."""
    id: str
    organization_id: str
    email: str
    role: Literal['admin', 'member', 'annotator', 'viewer']
    status: Literal['pending', 'accepted', 'expired', 'revoked']
    invited_by: str | None = None
    expires_at: datetime
    created_at: datetime

The invite token is never exposed - invitees follow the link in their email.

invite

Invite a new member by email, sending the invite email server-side. role is admin / member (default) / viewer - owners cannot be invited, only promoted after they accept. Requires admin or owner.

Source: Organizations.invite

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

pictograph organizations invite new@example.com --role member

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

class OrganizationInvite(BaseModel):
    """A pending / accepted / expired / revoked invite."""
    id: str
    organization_id: str
    email: str
    role: Literal['admin', 'member', 'annotator', 'viewer']
    status: Literal['pending', 'accepted', 'expired', 'revoked']
    invited_by: str | None = None
    expires_at: datetime
    created_at: datetime

The email is lowercased and trimmed server-side, and the member cap counts existing members plus pending invites against the tier’s max_users.

revoke_invite

Revoke a pending invite immediately. Requires admin or owner.

Source: Organizations.revoke_invite

client.organizations.revoke_invite(
    invite_id="f2a3b4c5-6d7e-4f89-a012-b3c4d5e6f7a8",
)

pictograph organizations invite-revoke f2a3b4c5-6d7e-4f89-a012-b3c4d5e6f7a8 --yes

curl -s -X DELETE "https://api.pictograph.io/api/v1/developer/organizations/invites/f2a3b4c5-6d7e-4f89-a012-b3c4d5e6f7a8" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns None

Permissions

Common errors