equinorequinor/fusion-skills/skills/fusion-help-api/SKILL.md

fusion-help-api

Skill2 starsChanged 2 months agoMITView on GitHub

Guides developers and admins through direct interaction with the Fusion Help REST API — reading articles, FAQs, release notes, searching content, and managing help documentation programmatically. USE FOR: fetch help articles from API, integrate help content in app, search help content, manage help documentation via API, automate help content, build help tooling. DO NOT USE FOR: using the fhelp CLI tool (use fusion-help-docs skill), modifying Fusion.Services.Help backend code, or non-help-API tasks.

In this repository31 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- caveman-compressSkill
- fusion-core-servicesSkill
- fusion-dependency-reviewSkill
- fusion-designSkill
- fusion-framework-mockingSkill
- fusion-framework-testingSkill
- fusion-github-review-resolutionSkill
- fusion-issue-solvingSkill
- fusion-issue-task-planningSkill
- fusion-mcpSkill
- fusion-package-scribeSkill
- fusion-pm-mcpSkill
- fusion-backend-devSkill
- fusion-developer-appSkill
- fusion-developer-portalSkill
- fusion-devtoolsSkill
- fusion-help-docsSkill
- fusion-help-integrationSkill
- fusion-infra-cliSkill
- fusion-issue-authoringSkill
- fusion-roles-cliSkill
- fusion-rulesSkill
- fusion-skill-authoringSkill
- fusionSkill
- fusion-skillsSkill
- equinor-design-systemSkill
- fusion-code-conventionsSkill
- fusion-researchSkill
- fusion-rule-authorSkill

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 5 are distinctive, and 4 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Use when a developer or admin needs to interact directly with the Fusion Help REST API — reading help content, building custom tooling, or …
line 22
Distinctive:
Search or suggest help content from an application
line 29
Distinctive:
Read help content for another system
line 31
Very specific:
Look for the service with key: "help" in the response.
line 66
Distinctive:
All endpoints require a valid Azure AD bearer token.
line 70
Distinctive:
Read-only endpoints are safe for any authenticated user — no admin permissions needed
line 113
Very specific:
Write operations require app admin, trusted application, or Fusion.Help.FullControl
line 114
Very specific:
Always test against ci before targeting fprd
line 117
Very specific:
Never hardcode bearer tokens — use DefaultAzureCredential or equivalent
line 118

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Fusion Help API

Use when a developer or admin needs to interact directly with the Fusion Help REST API — reading help content, building custom tooling, or automating content management.

When to use

Display help articles, FAQs, or release notes inside a Fusion app
Build custom CLI or automation to manage help content
Programmatically create, update, or delete help documentation
Search or suggest help content from an application
Understand Help API endpoints, authentication, or data models
Read help content for another system

When not to use

Using fhelp CLI to sync markdown docs → use fusion-help-docs
Modifying Fusion.Services.Help backend service code
General REST API questions unrelated to Help

Required inputs

Input	Required	Description
Use case	Yes	Reading content, managing content, or searching
App key	For scoped queries	The Fusion app key to read/manage help for
Target environment	Yes	`ci`, `fqa`, `tr`, or `fprd`
Auth context	Yes	User token (interactive) or service principal (automation)

Instructions

1. Discover the Help API base URL

Resolve URL dynamically or use known patterns:

Environment	Base URL
`ci`	`https://help.ci.api.fusion-dev.net`
`fqa`	`https://help.fqa.api.fusion-dev.net`
`fprd`	`https://help.api.fusion.equinor.com`

Dynamic discovery (recommended for production tooling):

GET https://discovery.fusion.equinor.com/service-registry/environments/{env}/services

Look for the service with key: "help" in the response. Use the uri field as the base URL.

2. Authentication

All endpoints require a valid Azure AD bearer token. Token audiences and code samples for frontend, backend, and CLI are in references/authentication.md.

Quick reference — token audiences:

Environment	Resource ID (audience)
`ci`, `fqa`, `tr`	`5a842df8-3238-415d-b168-9f16a6a6031b/.default`
`fprd`	`97978493-9777-4d48-b38a-67b0b9cd88d2/.default`

3. Authorization levels

Action	Who can do it
Read articles, FAQs, release notes, search	Any authenticated Fusion user
Create / Update / Delete articles, FAQs, release notes	App admin, trusted app, or `Fusion.Help.FullControl`
Upload assets (images)	App admin, trusted app, or `Fusion.Help.FullControl`
View changelog (global)	`Fusion.Help.FullControl` only
View changelog (per app)	App admin or `Fusion.Help.FullControl`

4. Call the API

Endpoints are versioned — include ?api-version=1.0. Resources: Articles, FAQs, Release Notes, Assets, Search/Suggest, Changelog.

For full CRUD details, request/response bodies, OData filters, and validation rules see references/api-endpoints.md.

For compact endpoint matrix and OData cheat sheet see references/api-quick-reference.md.

For response model schemas see references/response-models.md.

5. Integration patterns

Ready-to-use code samples (React component, release notes banner, FAQ search, C# backend automation, Python scripting) are in references/integration-patterns.md.

Expected output

Working code to authenticate and call the Help API
Correct endpoint URLs and query parameters for the use case
Understanding of response models and OData query options
For admin use cases: correct request bodies for create/update/delete
For integration patterns: sample code in the relevant language/framework

Safety & constraints

Read-only endpoints are safe for any authenticated user — no admin permissions needed
Write operations require app admin, trusted application, or Fusion.Help.FullControl
Deleted articles/FAQs/release notes are soft-deleted — slugs cannot be reused
sourceSystem tracks which tool created a record — mixing source systems for the same slug causes fhelp CLI to refuse updates (unless --no-validation is used)
Always test against ci before targeting fprd
Never hardcode bearer tokens — use DefaultAzureCredential or equivalent
Image uploads must be PNG; API processes them into WebP for serving

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free