> ## Documentation Index > Fetch the complete documentation index at: https://docs.galinum.com/llms.txt > Use this file to discover all available pages before exploring further. # Claim GitHub source work > Refreshes source evidence and grants a bounded lease, or settles lifecycle work without model execution. Read the returned state before acting. Available in Galinum Cloud. ## OpenAPI ````yaml /openapi.json post /api/v1/github/refs/{refId}/claim openapi: 3.1.0 info: title: Galinum API version: '2026-08-22' description: >- Galinum's HTTP API. SDK endpoints power the browser SDK. Management endpoints use a project secret. The scoped hosted-agent credential writes only through lease-fenced evaluation and GitHub source endpoints. Managed-only operations return 501 on the self-host server. servers: - url: https://galinum.com description: Production security: - publishableKey: [] paths: /api/v1/github/refs/{refId}/claim: post: tags: - GitHub sources summary: Claim GitHub source work description: >- Refreshes source evidence and grants a bounded lease, or settles lifecycle work without model execution. Read the returned state before acting. Available in Galinum Cloud. operationId: claimGithubRef parameters: - name: refId in: path required: true schema: type: string minLength: 1 maxLength: 128 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GithubClaimRequest' responses: '200': description: The successful source-work result. content: application/json: schema: $ref: '#/components/schemas/GithubClaimResult' '400': description: Invalid source request. content: application/json: schema: $ref: '#/components/schemas/GithubSourceError' '401': $ref: '#/components/responses/Unauthorized' '403': description: The source policy or lease refuses this action. content: application/json: schema: $ref: '#/components/schemas/GithubSourceError' '404': description: The source ref is not available in this project. content: application/json: schema: $ref: '#/components/schemas/GithubSourceError' '409': description: The work, coverage, or current campaign conflicts with this request. content: application/json: schema: $ref: '#/components/schemas/GithubSourceError' '413': $ref: '#/components/responses/TooLarge' '429': $ref: '#/components/responses/RateLimited' '503': description: Source evidence is unavailable. content: application/json: schema: $ref: '#/components/schemas/GithubSourceError' security: - secretKey: [] - hostedAgentKey: [] components: schemas: GithubClaimRequest: type: object properties: leaseSeconds: default: 600 type: integer minimum: 30 maximum: 900 required: [] additionalProperties: false GithubClaimResult: oneOf: - type: object additionalProperties: false required: - ok - state - claim properties: ok: const: true state: const: claimed claim: type: object additionalProperties: false required: - refId - sourceId - sourceGeneration - instructions - leaseToken - expiresAt - fromSha - toSha - complete - comparison - repositoryContext - files - changes - withdrawals - drafts properties: refId: type: string sourceId: type: string sourceGeneration: type: integer minimum: 0 instructions: type: string maxLength: 8000 leaseToken: type: string expiresAt: type: integer minimum: 0 fromSha: type: string pattern: ^[a-f0-9]{40}$ toSha: type: string pattern: ^[a-f0-9]{40}$ complete: const: true comparison: type: object additionalProperties: false required: - beforeSha - afterSha properties: beforeSha: type: string pattern: ^[a-f0-9]{40}$ afterSha: type: string pattern: ^[a-f0-9]{40}$ repositoryContext: type: object additionalProperties: false required: - description - readme - commitSha properties: description: anyOf: - type: string - type: 'null' readme: anyOf: - type: string - type: 'null' commitSha: type: string pattern: ^[a-f0-9]{40}$ files: type: array items: type: object additionalProperties: false required: - path - patch properties: path: type: string patch: anyOf: - type: string - type: 'null' changes: type: array items: type: object additionalProperties: false required: - sha - message - pullRequests - sourceCampaignIds properties: sha: type: string pattern: ^[a-f0-9]{40}$ message: type: string pullRequests: type: array items: type: object additionalProperties: false required: - number - mergedHeadSha properties: number: type: integer minimum: 0 mergedHeadSha: anyOf: - type: string pattern: ^[a-f0-9]{40}$ - type: 'null' sourceCampaignIds: type: array items: type: string withdrawals: type: array items: type: object additionalProperties: false required: - campaignId - contributions - patch properties: campaignId: type: string contributions: type: array items: type: object additionalProperties: false required: - id - ordinal - withdrawn - edits properties: id: type: string ordinal: type: integer minimum: 0 withdrawn: type: boolean edits: type: array items: type: object additionalProperties: false required: - variantId - field - before - after properties: variantId: type: string field: type: string enum: - title - body - subject - previewText - cta.label - cta.url - cta.destination.kind - cta.destination.url before: anyOf: - type: string - type: 'null' after: type: string patch: type: object properties: name: type: object properties: before: type: string minLength: 1 maxLength: 80 after: type: string minLength: 1 maxLength: 80 required: - before - after additionalProperties: false variants: minItems: 1 maxItems: 10 type: array items: type: object properties: id: type: string minLength: 1 maxLength: 128 edits: minItems: 1 maxItems: 20 type: array items: type: object properties: field: type: string enum: - title - body - subject - previewText - cta.label - cta.url - cta.destination.kind - cta.destination.url before: type: string minLength: 1 maxLength: 16384 after: type: string maxLength: 16384 required: - field - before - after additionalProperties: false required: - id - edits additionalProperties: false additionalProperties: false drafts: type: array items: type: object additionalProperties: false required: - campaignId - origin - contentHash - customerEditedFields - review - campaign properties: campaignId: type: string origin: type: string enum: - source - customer contentHash: type: string pattern: ^[a-f0-9]{64}$ customerEditedFields: type: array items: type: string review: type: string enum: - pending - approved campaign: $ref: '#/components/schemas/CampaignDetail' - type: object additionalProperties: false required: - ok - state - refId properties: ok: const: true state: const: settled refId: type: string GithubSourceError: type: object additionalProperties: false required: - ok - status - error properties: ok: const: false status: type: integer enum: - 400 - 403 - 404 - 409 - 503 error: type: string retryAfterMs: type: integer minimum: 0 CampaignDetail: allOf: - $ref: '#/components/schemas/Campaign' - type: object required: - variants - sourceChanges properties: variants: type: array items: type: object required: - id - name - weight - isControl - content - stats properties: id: type: string example: var_37705a49-52c6-4577-aeed-665099a1e13d name: type: string example: A weight: type: number example: 1 isControl: type: boolean content: $ref: '#/components/schemas/StoredMessageContent' stats: $ref: '#/components/schemas/CampaignStats' sourceChanges: $ref: '#/components/schemas/CampaignSourceChanges' Error: type: object required: - error properties: error: type: string description: Human-readable description of what went wrong. Campaign: type: object required: - id - name - status - effectiveStatus - channel - goalId - createdBy - createdAt - startedAt - endedAt - deliverFrom - deliverUntil - audience - targeting - pages - stats properties: id: type: string example: cmp_3ce6dba5-7f36-41f5-9327-d5cc3099ab77 name: type: string example: 'Launch: CSV export' status: type: string enum: - draft - running - paused - ended description: Stored lifecycle status. effectiveStatus: type: string enum: - draft - scheduled - running - paused - expired - ended description: >- Lifecycle status refined by the delivery window, always current: `scheduled` = running before `deliverFrom`, `expired` = running/paused at or after `deliverUntil` (expiry outranks paused). channel: type: string enum: - web_inapp - email - push example: web_inapp goalId: type: - string - 'null' description: >- The goal this campaign serves, or null. When set, tracked events matching the goal's targetEvent automatically resolve exposed deliveries to converted. Exposure is shownAt for web in-app and deliveredAt for email. createdBy: type: string description: >- Who created the campaign: a dashboard user (`human`), this API (`api`), or the Galinum agent (`agent`). example: api createdAt: type: integer description: Epoch milliseconds. example: 1784067764978 startedAt: type: - integer - 'null' description: Epoch milliseconds. endedAt: type: - integer - 'null' description: Epoch milliseconds. deliverFrom: type: - integer - 'null' description: >- Requested delivery-window start, epoch milliseconds (null = starts when launched). deliverUntil: type: - integer - 'null' description: >- Requested delivery-window end, epoch milliseconds (null = delivers until ended). audience: $ref: '#/components/schemas/CampaignAudience' targeting: anyOf: - $ref: '#/components/schemas/Targeting' - type: 'null' deprecated: true description: >- Deprecated legacy targeting shape, present only for campaigns still stored with it (null otherwise). Read `audience` instead. pages: type: - array - 'null' items: type: string description: >- Web in-app path patterns, or null. Email campaigns always return null. example: - /dashboard - /settings/* stats: $ref: '#/components/schemas/CampaignStats' push: oneOf: - $ref: '#/components/schemas/PushSettings' - type: 'null' StoredMessageContent: oneOf: - $ref: '#/components/schemas/StoredWebInAppMessageContent' - $ref: '#/components/schemas/EmailMessageInput' CampaignStats: type: object required: - sent - frequencyCapped - delivered - shown - opened - clicked - dismissed - bounced - complained - unsubscribed - converted properties: sent: type: integer frequencyCapped: type: integer description: >- Campaign-email recipients skipped by the project-wide rolling 24-hour frequency limit. delivered: type: integer shown: type: integer opened: type: integer clicked: type: integer dismissed: type: integer bounced: type: integer complained: type: integer unsubscribed: type: integer converted: type: integer CampaignSourceChanges: type: object additionalProperties: false required: - revision - changes properties: revision: type: string changes: type: array items: $ref: '#/components/schemas/CampaignSourceChange' description: >- Complete current associations and their revision. Read arrays are not truncated or restricted by ordinary write-size limits, including when deployment evidence is unknown or manual launch is required. CampaignAudience: oneOf: - type: object required: - kind properties: kind: const: all description: Everyone — every identified user. - type: object required: - kind - audienceVersionId - schemaVersion - expression - expressionHash - summary - reason - legacy properties: kind: const: expression audienceVersionId: type: - string - 'null' description: >- The pinned immutable audience version (aud_…). Null only for campaigns still stored with the deprecated legacy targeting shape. schemaVersion: type: integer expression: $ref: '#/components/schemas/AudienceExpression' description: The exact canonical expression used. expressionHash: type: string description: sha256 of the canonical expression. summary: type: string description: Deterministically derived readable summary. reason: type: - string - 'null' description: Why this audience version was created. legacy: type: boolean description: >- True when derived from a stored legacy targeting shape rather than a pinned audience version. - type: object required: - kind - audienceVersionId properties: kind: const: invalid audienceVersionId: type: - string - 'null' description: >- The stored audience cannot be read (fails validation). The campaign delivers to NOBODY until the audience is replaced — invalid audiences fail closed, never widen to everyone. - type: object required: - kind - audienceVersionId - segmentId - segmentKey - segmentVersion - schemaVersion - expression - expressionHash - summary - reason properties: kind: const: segment audienceVersionId: type: string description: The pinned immutable audience version. segmentId: type: string segmentKey: type: - string - 'null' segmentVersion: type: integer description: >- The exact pinned version — later segment revisions never change it. schemaVersion: type: integer expression: $ref: '#/components/schemas/AudienceExpression' description: The exact expression in effect. expressionHash: type: string summary: type: string reason: type: - string - 'null' description: A saved segment version pinned by this campaign. description: >- The campaign's effective audience: everyone (`all`), a pinned inline expression, a pinned saved segment version (`segment`), or `invalid` (fail-closed). Targeting: type: object description: >- Audience rules. All conditions must match. An empty object (or null) matches everyone. properties: traits: type: object additionalProperties: oneOf: - type: string - type: number - type: boolean description: Trait values the user must match by strict equality. example: plan: free events: type: object properties: seen: type: array items: type: string description: Events the user must have fired at least once. example: - activated_workspace not_seen: type: array items: type: string description: Events the user must NOT have fired. example: - used_csv_export PushSettings: type: object properties: appId: type: string minLength: 1 maxLength: 256 selection: oneOf: - type: object properties: kind: type: string enum: - last_active - all required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - specific installationId: type: string minLength: 1 maxLength: 128 required: - kind - installationId additionalProperties: false ttlSeconds: type: integer minimum: 1 maximum: 2419200 replacementKey: type: string minLength: 1 maxLength: 64 required: - appId - selection additionalProperties: false StoredWebInAppMessageContent: type: object description: >- The variant's stored message content. Same shape as the write schema, except `presentation` is absent on campaigns authored before it existed — reads return stored content verbatim. Delivery resolves one for those (media → `modal`, no media → `toast`). properties: presentation: type: string enum: - toast - modal description: >- How the built-in renderer presents the message; media is independent content. `toast` is the compact bottom-right card, `modal` the centered announcement over a full-screen backdrop. example: toast title: type: string maxLength: 120 example: CSV export is here 📊 body: type: string maxLength: 600 example: Export any table to CSV from the toolbar. cta: type: object required: - label properties: label: type: string example: Try it destination: type: object required: - kind - url additionalProperties: false properties: kind: type: string enum: - website - app url: type: string description: >- HTTPS website URL, or an app URL whose scheme is configured in the client. example: https://app.example.com/exports media: $ref: '#/components/schemas/MessageMedia' EmailMessageInput: type: object required: - subject - body description: >- Email campaign content. The body is Markdown and Galinum adds the project compliance footer. properties: subject: type: string maxLength: 200 example: CSV export is ready previewText: type: string maxLength: 200 example: Download any table in one click body: type: string maxLength: 50000 description: Markdown email body. example: '# CSV export is here\n\nDownload any table from the toolbar.' cta: type: object required: - label - url properties: label: type: string example: Try CSV export url: type: string format: uri description: Must use http:// or https://. example: https://app.example.com/exports CampaignSourceChange: oneOf: - type: object additionalProperties: false required: - sourceId - kind - sha properties: sourceId: type: string minLength: 1 maxLength: 128 kind: type: string const: commit sha: type: string pattern: ^[a-f0-9]{40}$ - type: object additionalProperties: false required: - sourceId - kind - number - shas properties: sourceId: type: string minLength: 1 maxLength: 128 kind: type: string const: pull_request number: type: integer minimum: 1 shas: type: array minItems: 1 items: type: string pattern: ^[a-f0-9]{40}$ description: >- One current source association. PR shas include the complete original commit set; read projections do not apply input array-size limits. AudienceExpression: type: object required: - version - root properties: version: type: integer enum: - 1 description: Audience expression schema version. root: $ref: '#/components/schemas/AudienceNode' additionalProperties: false description: >- Versioned, strictly validated audience rule. Example: `{ "version": 1, "root": { "kind": "all", "children": [ { "kind": "field", "field": { "kind": "trait", "key": "plan" }, "op": "eq", "value": "free" }, { "kind": "not", "child": { "kind": "event", "event": "used_csv_export" } } ] } }` example: version: 1 root: kind: all children: - kind: field field: kind: trait key: plan op: eq value: free - kind: not child: kind: event event: used_csv_export MessageMedia: type: object required: - url description: >- Optional image for a message (PNG, JPEG, WebP, or animated GIF). Media is content, not presentation: a toast shows it as a compact thumbnail and a modal shows it as the immersive visual. Exactly one of `alt` or `decorative: true` is required. oneOf: - required: - alt properties: decorative: const: false - required: - decorative properties: decorative: const: true not: required: - alt properties: url: type: string format: uri pattern: ^https?:// description: >- A managed campaign media URL returned by POST /api/v1/campaign-media for this project. External, data:, and other projects' URLs are rejected. example: >- https://galinum.example/media/projects/prj_123/media/9c2f0b7e-4d11-4c2a-a3d1-1c9a1a2b3c4d.png alt: type: string maxLength: 300 description: >- What the image shows, for assistive technology. Required unless `decorative` is true. example: Screenshot of the new analytics dashboard decorative: type: boolean description: >- Mark the image as purely decorative instead of providing alt text. Mutually exclusive with `alt`. AudienceNode: oneOf: - type: object required: - kind - children additionalProperties: false properties: kind: const: all children: type: array minItems: 1 maxItems: 16 items: $ref: '#/components/schemas/AudienceNode' description: Every child must match. - type: object required: - kind - children additionalProperties: false properties: kind: const: any children: type: array minItems: 1 maxItems: 16 items: $ref: '#/components/schemas/AudienceNode' description: At least one child must match. - type: object required: - kind - child additionalProperties: false properties: kind: const: not child: $ref: '#/components/schemas/AudienceNode' description: Negates one child condition. - type: object required: - kind - field - op additionalProperties: false properties: kind: const: field field: $ref: '#/components/schemas/AudienceFieldRef' op: type: string enum: - eq - neq - in - not_in - contains - starts_with - ends_with - gt - gte - lt - lte - exists - not_exists - before - after - within_last - not_within_last value: description: >- Required for every operator except exists/not_exists (which reject it). Typed per operator: eq/neq take a string/number/boolean; in/not_in a non-empty array (≤ 50) of all strings or all numbers; contains/starts_with/ends_with a string; gt/gte/lt/lte a number; before/after an ISO-8601 date-time with explicit offset; within_last/not_within_last an AudienceWindow. description: >- Compares a user trait or lifecycle field. Comparisons are strict — no type coercion; a value comparison on an absent or type-incompatible field does not match (use exists/not_exists for absence). Lifecycle fields accept only datetime and existence operators. - type: object required: - kind - event additionalProperties: false properties: kind: const: event event: type: string maxLength: 80 count: type: object required: - op - value additionalProperties: false properties: op: type: string enum: - eq - neq - gt - gte - lt - lte value: type: integer minimum: 0 maximum: 10000 description: >- Occurrence-count comparison; defaults to at-least-once ({ op: gte, value: 1 }). window: $ref: '#/components/schemas/AudienceWindow' where: type: array minItems: 1 maxItems: 8 items: $ref: '#/components/schemas/AudienceNode' description: field nodes on event_property references, ANDed per occurrence. description: >- Evaluates occurrences of one event, optionally within a relative window and filtered by event-property conditions. description: >- One audience expression node, discriminated by `kind`. Overall limits: nesting depth ≤ 8, total nodes ≤ 64. Unknown kinds, unknown operators, unknown keys, and empty groups are rejected with structured diagnostics. AudienceFieldRef: oneOf: - type: object required: - kind - key properties: kind: const: trait key: type: string maxLength: 128 description: Literal top-level trait key. additionalProperties: false - type: object required: - kind - field properties: kind: const: user field: type: string enum: - firstSeenAt - lastSeenAt description: Lifecycle field (datetime). additionalProperties: false - type: object required: - kind - key properties: kind: const: event_property key: type: string maxLength: 128 description: >- Literal top-level event property key. Only valid inside an event node's where conditions. additionalProperties: false description: Structured, unambiguous field reference. AudienceWindow: type: object required: - amount - unit properties: amount: type: integer minimum: 1 unit: type: string enum: - minutes - hours - days additionalProperties: false description: >- Relative time window measured back from the evaluation instant (evaluatedAt). responses: Unauthorized: description: >- Missing or invalid API key. SDK endpoints take the publishable key; management endpoints (campaigns, media, users, events, goals, agent runs) take the secret key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Unauthorized TooLarge: description: Request body exceeds the endpoint's size limit. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid request RateLimited: description: >- Rate limit exceeded, counted per project (SDK endpoints: 120 requests/minute or 2,000/hour per endpoint; management endpoints: 60/minute or 1,000/hour per resource group — all campaign operations share one budget, as do goal operations and user reads). Retry after the `Retry-After` header. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Too many requests securitySchemes: publishableKey: type: http scheme: bearer description: >- Your project's publishable key (`pk_pub_…`). Safe to expose in the browser — it identifies the project and is rate-limited, not secret. secretKey: type: http scheme: bearer description: >- Your project's secret key (`pk_…`, without the `pub` segment). Server-side only — never ship it to a browser. Get it from Settings → Projects in the dashboard. hostedAgentKey: type: http scheme: bearer description: >- Galinum's scoped hosted-agent key (pk_agent_...). It can read required project state, including launch policy and campaign activation, and use fenced evaluation or GitHub source operations. Ordinary campaign, status, goal, segment, media, launch-policy, and campaign-activation writes return 403. Reads grant no approval or deployment configuration authority. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.