Skip to main content

AgentRef Python SDK

Official Python SDK for the AgentRef REST API v1.

Install

pip install agentref

Quickstart

from agentref import AgentRef

client = AgentRef(api_key="ak_live_...")
programs = client.programs.list()
print(programs.meta.request_id)

Async quickstart

from agentref import AsyncAgentRef

async with AsyncAgentRef(api_key="ak_live_...") as client:
    programs = await client.programs.list()

Affiliate workspace quickstart

from agentref import AgentRef

client = AgentRef(api_key="ak_aff_...")
overview = client.affiliate_workspace.overview()
programs = client.affiliate_workspace.list_programs()

if programs:
    detail = client.affiliate_workspace.get_program(programs[0].program_id)
    link = client.affiliate_workspace.create_link(
        name="Pricing",
        destination_path="/pricing",
        custom_slug="jane-review",
        program_id=detail.program_id,
        idempotency_key="create-pricing-link",
    )
    print(overview.program_count, detail.program_name, link["code"])

Authentication

  • Uses Authorization: Bearer <key>.
  • Supports ak_onb_*, ak_live_*, ak_aff_*.
  • Provide api_key directly or set AGENTREF_API_KEY.

Resources

  • client.programs: list, list_all, get, create, update, delete, stats, list_affiliates, list_coupons, create_coupon, delete_coupon, list_invites, create_invite, update_marketplace, connect_stripe, disconnect_stripe
  • client.applications: list, get, approve, decline, block
  • client.affiliate_workspace: overview, identity, list_programs, get_program, earnings, list_program_earnings, list_payouts, list_links, create_link, update_link, delete_link, click_stats
  • client.marketing_resources: list, create_social_post, update_social_post, create_social_post_media_upload_session, complete_social_post_media_upload, reorder_social_post_media, update_social_post_media, remove_social_post_media, replace_social_post_media, publish, unpublish, archive, notify_affiliates, create_download_url, list_for_affiliate, get_for_affiliate, create_affiliate_download_url, render_social_post
  • client.affiliates: list, get, block, unblock
  • client.conversions: list, stats, recent
  • client.payouts: list, list_pending, stats, create
  • client.flags: list, stats, resolve
  • client.billing: current, tiers, subscribe
  • client.merchant: get, update
  • client.notifications: get, update
  • client.payout_info: get, update
  • client.onboarding: upsert_merchant_profile, complete
  • client.tracking: get_program_status
  • client.invites: get, claim
  • client.marketplace: list_programs, apply
  • client.webhooks: list, create, get, update, delete, rotate_secret

Applications

Pending affiliate joins are application records. Use client.applications to approve, decline, or block applications before they become approved affiliate memberships.

pending = client.applications.list(program_id="prog-uuid", status="pending")
client.applications.approve(
    pending.data[0].id,
    note="Relevant SaaS audience.",
    idempotency_key="approve-app-1",
)

Marketing Resources

Merchant keys can manage resources. Affiliate keys can list, download, and render published resources for joined programs.

post = client.marketing_resources.create_social_post(
    "prog-uuid",
    title="Launch copy",
    body="Try AgentRef: {{affiliate_link}}",
    platforms=["linkedin"],
    status="published",
    idempotency_key="mr-social-launch",
)

client.marketing_resources.publish(
    post["id"],
    program_id="prog-uuid",
    notify_affiliates=True,
    idempotency_key="publish-mr-social-launch",
)

rendered = client.marketing_resources.render_social_post(
    post["id"],
    program_id="prog-uuid",
    affiliate_link_id="link-uuid",
)

Marketplace, Invites, Onboarding, and Tracking

client.onboarding.upsert_merchant_profile(company_name="Acme Inc.")
client.onboarding.complete()

tracking = client.tracking.get_program_status("prog-uuid")
invite = client.invites.get("invite-token")
claimed = client.invites.claim(invite["token"])

marketplace = client.marketplace.list_programs(sort="commission")
client.marketplace.apply(
    marketplace.data[0]["programId"],
    message="I manage affiliate agents for SaaS products.",
)

Pagination

List endpoints return PaginatedResponse[T] with:

  • meta.total
  • meta.page
  • meta.page_size
  • meta.has_more
  • meta.next_cursor
  • meta.request_id

Auto-pagination (list_all) stops on has_more is False.

Idempotency and retry behavior

  • GET/HEAD: auto-retry on 429/5xx.
  • POST: auto-retry only when idempotency_key is provided.
  • PATCH/DELETE: never auto-retry.
  • Idempotency-Key header is sent only for POST requests.

Error handling

from agentref import AgentRef
from agentref.errors import ForbiddenError, NotFoundError, RateLimitError, AgentRefError

client = AgentRef(api_key="ak_live_...")

try:
    client.programs.get("missing-id")
except ForbiddenError as e:
    print(e.code, e.request_id)
except NotFoundError as e:
    print(e.request_id)
except RateLimitError as e:
    print(e.retry_after)
except AgentRefError as e:
    print(e.status)

Configuration

Option Default Description
api_key AGENTREF_API_KEY API key
base_url https://www.agentref.co/api/v1 Base API URL
timeout 30.0 Request timeout in seconds
max_retries 2 Retry count for GET/HEAD and POST+idempotency_key

Metadata

Release files for agentref 5.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentref 5.1.2
File Size Uploaded Provenance Actions
agentref-5.1.2.tar.gz 24.9 kB With provenance Details for agentref-5.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentref 5.1.2
File Interpreter ABI Platform Actions
agentref-5.1.2-py3-none-any.whl Python 3 none any Details for agentref-5.1.2-py3-none-any.whl

Total release size: 53.4 kB

Release files / agentref-5.1.2.tar.gz

Download URL agentref-5.1.2.tar.gz
Size 24.9 kB
Tags Source
SHA-256 checksum
How to use checksums
f9f247db837b389c853a391830f95c3d341ec2f22c7698f843c02946512209e7
BLAKE2b-256 checksum
How to use checksums
f609a25af43fdc141150c7b6218f079ce898ae64f2fee11aa51e19b0b1bbe04d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 8, 2026.

Transparency log

Release files / agentref-5.1.2-py3-none-any.whl

Download URL agentref-5.1.2-py3-none-any.whl
Size 28.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6f35c89055f1ceda5945d99fa4753224d8e875eaa5c6397a8c342e924f8db388
BLAKE2b-256 checksum
How to use checksums
5582b0c9c0a7411918de1960119178370d41cf1bb7b0453dea06e284bc892641
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 8, 2026.

Transparency log

Security for agentref 5.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agentref-5.1.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page